@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,55 @@
+/**
+ * Image render decision — testable render logic for <Img>.
+ *
+ * Picks the `src` + responsive `srcset` for a catalog image, factored out of
+ * Img.astro so the branching is unit-testable without rendering the component:
+ *   - unusable/missing URL  -> deterministic placeholder data URI
+ *   - rehosted (R2)         -> Cloudflare Image Resizing (/cdn-cgi/image, format=auto)
+ *   - referenced Shopify CDN -> Shopify's native ?width= scheme
+ *   - anything else usable   -> the URL as-is, no srcset
+ */
+import { placeholderDataUri, isUsableImageUrl } from "./placeholder.js";
+import { cfImageUrl, cfImageSrcset, CF_IMAGE_WIDTHS } from "./cfImage.js";
+
+export interface ResolveImageInput {
+  src?: string;
+  rehosted?: boolean;
+  width: number;
+  height: number;
+  /** Placeholder seed (image id / product handle). */
+  seed: string;
+  label?: string;
+}
+
+export interface ResolvedImage {
+  src: string;
+  srcset?: string;
+}
+
+const isShopifyCdnUrl = (url: string): boolean =>
+  /\/\/cdn\.shopify\.com\//.test(url) || /\/cdn\/shop\//.test(url);
+
+export function resolveImage(input: ResolveImageInput): ResolvedImage {
+  const { src, rehosted = false, width, height, seed, label } = input;
+
+  if (!isUsableImageUrl(src, rehosted)) {
+    return { src: placeholderDataUri({ seed, width, height, label }) };
+  }
+  const url = src!;
+
+  // Rehosted (R2) images go through Cloudflare Image Resizing — true resizing +
+  // format=auto (AVIF/WebP).
+  if (rehosted) {
+    return { src: cfImageUrl(url, { width }), srcset: cfImageSrcset(url, width) };
+  }
+
+  // Referenced Shopify CDN URLs already resize via ?width=; keep that scheme.
+  if (isShopifyCdnUrl(url)) {
+    const srcset = CF_IMAGE_WIDTHS.filter((w) => w <= width * 2)
+      .map((w) => `${url}${url.includes("?") ? "&" : "?"}width=${w} ${w}w`)
+      .join(", ");
+    return { src: url, srcset };
+  }
+
+  return { src: url };
+}

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

@@ -0,0 +1,166 @@
+/**
+ * schema.org JSON-LD builders (brief §8): Product (with offers),
+ * BreadcrumbList, Organization. Kept pure so pages compose them and pass to <Seo>.
+ */
+import type { CatalogProduct, Review, TenantConfig } from "@tot/public-runtime";
+import { isAvailable } from "./tot/query.js";
+
+export function organizationLd(tenant: TenantConfig, base: string) {
+  // Logo sourced from the migrated brand assets (og image / logo), so the
+  // Organization schema reflects the real merchant brand, not a generic favicon.
+  const brand = tenant.theme_tokens?.brand;
+  const logo =
+    brand?.ogImage ?? brand?.logoLight ?? new URL("/favicon.svg", base + "/").toString();
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: tenant.displayName,
+    url: base,
+    logo,
+  };
+}
+
+/** ItemList — the ordered products on a collection/PLP page. */
+export function itemListLd(
+  products: CatalogProduct[],
+  base: string,
+  pageOffset = 0,
+) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "ItemList",
+    numberOfItems: products.length,
+    itemListElement: products.map((p, i) => ({
+      "@type": "ListItem",
+      position: pageOffset + i + 1,
+      url: new URL(`/products/${p.handle}`, base + "/").toString(),
+      name: p.title,
+    })),
+  };
+}
+
+/**
+ * WebSite + SearchAction — enables Google's sitelinks search box, wired to the
+ * storefront's own /search?q= endpoint.
+ */
+export function websiteLd(tenant: TenantConfig, base: string) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: tenant.displayName,
+    url: base,
+    potentialAction: {
+      "@type": "SearchAction",
+      target: {
+        "@type": "EntryPoint",
+        urlTemplate: `${base.replace(/\/$/, "")}/search?q={search_term_string}`,
+      },
+      "query-input": "required name=search_term_string",
+    },
+  };
+}
+
+export function breadcrumbLd(
+  crumbs: { label: string; href: string }[],
+  base: string,
+) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: crumbs.map((c, i) => ({
+      "@type": "ListItem",
+      position: i + 1,
+      name: c.label,
+      item: new URL(c.href, base + "/").toString(),
+    })),
+  };
+}
+
+export function productLd(
+  p: CatalogProduct,
+  tenant: TenantConfig,
+  base: string,
+) {
+  const url = new URL(`/products/${p.handle}`, base + "/").toString();
+  const images = p.images
+    .map((i) => i.url)
+    .filter((u) => !/cdn\.shopify\.com/.test(u)); // skip dead fixture URLs
+
+  const offers = p.variants.map((v) => ({
+    "@type": "Offer",
+    sku: v.sku,
+    price: v.price.toFixed(2),
+    priceCurrency: v.currency,
+    availability: v.inventory.available
+      ? "https://schema.org/InStock"
+      : "https://schema.org/OutOfStock",
+    url,
+  }));
+
+  const ratingMf = p.metafields.find(
+    (m) => m.namespace === "reviews" && m.key === "rating",
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: p.title,
+    description: p.seo.description || p.description_text.slice(0, 300),
+    sku: p.variants[0]?.sku,
+    ...(images.length ? { image: images } : {}),
+    ...(p.vendor ? { brand: { "@type": "Brand", name: p.vendor } } : {}),
+    ...(p.product_type ? { category: p.product_type } : {}),
+    offers: {
+      "@type": "AggregateOffer",
+      priceCurrency: p.price_range.currency,
+      lowPrice: p.price_range.min.toFixed(2),
+      highPrice: p.price_range.max.toFixed(2),
+      offerCount: p.variants.length,
+      availability: isAvailable(p)
+        ? "https://schema.org/InStock"
+        : "https://schema.org/OutOfStock",
+      offers,
+    },
+    ...(ratingMf
+      ? {
+          aggregateRating: {
+            "@type": "AggregateRating",
+            ratingValue: ratingMf.value,
+            bestRating: "5",
+            // ASSUMPTION: review count placeholder; real capture is Phase 2.
+            ratingCount: 24,
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * Review markup policy (docs/architecture/review-markup-policy.md): only ever
+ * emit `aggregateRating`/`review` from REAL sourced numbers. `average`/`count`
+ * must be the real migrated aggregate (0 disables the field — never emit a
+ * fabricated `ratingCount` the way `productLd`'s metafield fallback still does).
+ * `reviews` are capped at 10 to keep the Product payload bounded; pass them in
+ * source order (most-relevant-first is the caller's job, not this builder's).
+ */
+export function reviewLd(average: number, count: number, reviews: Review[]) {
+  const out: Record<string, unknown> = {};
+  if (average > 0 && count > 0) {
+    out.aggregateRating = {
+      "@type": "AggregateRating",
+      ratingValue: average,
+      reviewCount: count,
+    };
+  }
+  if (reviews.length > 0) {
+    out.review = reviews.slice(0, 10).map((r) => ({
+      "@type": "Review",
+      reviewRating: { "@type": "Rating", ratingValue: r.rating, bestRating: 5 },
+      author: { "@type": "Person", name: r.author },
+      ...(r.title ? { name: r.title } : {}),
+      reviewBody: r.body,
+      ...(r.date ? { datePublished: r.date } : {}),
+    }));
+  }
+  return out;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Site-wide maintenance kill-switch.
+ *
+ * When `MAINTENANCE_MODE` is truthy the middleware returns {@link maintenanceResponse}
+ * for EVERY host and path — before tenant resolution, the access gate, the edge
+ * cache, or any render. It is a deliberate full close (a "Coming Soon" holding
+ * page), NOT a login gate: auth paths are not exempt, no tenant is resolved, and
+ * nothing tenant-specific is served. Use it as the fail-safe lever to take the
+ * whole storefront offline in one config flip.
+ *
+ * Back online: set `MAINTENANCE_MODE=0` (or unset it) and redeploy.
+ */
+
+/** True for "1" / "on" / "true" / "yes" (case/space-insensitive); false otherwise. */
+export function isMaintenanceOn(raw: string | null | undefined): boolean {
+  const v = (raw ?? "").trim().toLowerCase();
+  return v === "1" || v === "on" || v === "true" || v === "yes";
+}
+
+export const MAINTENANCE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex, nofollow" />
+<title>Coming soon</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100%; padding: 2rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: radial-gradient(1200px 800px at 50% -10%, #1e293b, #0f172a 60%, #020617);
+    color: #e2e8f0;
+  }
+  main { max-width: 34rem; text-align: center; }
+  .badge {
+    display: inline-block; letter-spacing: .18em; text-transform: uppercase;
+    font-size: .72rem; font-weight: 600; color: #94a3b8;
+    border: 1px solid rgba(148,163,184,.35); border-radius: 999px;
+    padding: .35rem .8rem; margin-bottom: 1.75rem;
+  }
+  h1 { font-size: clamp(2rem, 6vw, 3rem); line-height: 1.1; margin: 0 0 1rem; color: #f8fafc; }
+  p { font-size: 1.05rem; line-height: 1.6; color: #cbd5e1; margin: 0 auto; max-width: 28rem; }
+  .rule { width: 3rem; height: 3px; background: #38bdf8; border-radius: 2px; margin: 2rem auto 0; }
+</style>
+</head>
+<body>
+  <main>
+    <span class="badge">Token of Trust</span>
+    <h1>Coming soon</h1>
+    <p>We're putting the finishing touches on the storefront. It'll be back online shortly &mdash; thanks for your patience.</p>
+    <div class="rule"></div>
+  </main>
+</body>
+</html>`;
+
+/** A `503 Service Unavailable` holding page — cached nowhere, never indexed. */
+export function maintenanceResponse(): Response {
+  return new Response(MAINTENANCE_HTML, {
+    status: 503,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "retry-after": "3600",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}

package/apps/storefront/src/lib/membership/model.ts

@@ -0,0 +1,97 @@
+/**
+ * Membership / pricing tier model — the typed input for the platform tier
+ * widgets (<TierCards>, <TierComparisonTable>). These are presentational,
+ * EDUCATION-ONLY widgets: they render a tier/plan comparison (the
+ * Guest/Member/Autopilot pattern) but carry NO pricing, checkout, or
+ * subscription mechanics — a tenant wires the real subscribe/manage flow in the
+ * product/commerce layer and hands off to it via a plain CTA link.
+ *
+ * Because a tier's headline FIGURE (a price, a savings %, a "billed monthly"
+ * line) is a claim, the widgets treat figures as ILLUSTRATIVE by default: unless
+ * a tier explicitly asserts `real: true`, the widget marks its figures as
+ * illustrative ("e.g." affordance + a group-level "Illustrative figures" label)
+ * so example numbers are never presented as a live offer. This mirrors the
+ * platform-owned / never-faked discipline of the compliance widgets (decision
+ * `compliance-widgets-platform-owned`).
+ */
+
+/**
+ * A tier's headline figure (price, savings, or cadence line). Display only —
+ * this is a string the widget renders verbatim, NEVER a number it computes a
+ * price from. Marked illustrative unless the owning {@link Tier} sets `real`.
+ */
+export interface TierFigure {
+  /** The headline figure text, e.g. "$0", "$19/mo", "Save 15%". Display only. */
+  value: string;
+  /** Optional caption under the figure, e.g. "billed monthly". Display only. */
+  caption?: string;
+}
+
+/**
+ * One feature row shown on a tier card. `included` drives the check / dash glyph
+ * for a simple yes/no; omit it for a plain descriptive bullet.
+ */
+export interface TierFeature {
+  /** Feature text, e.g. "Free shipping over $50". */
+  label: string;
+  /** true → included (check), false → excluded (dash). Omit for a plain note. */
+  included?: boolean;
+}
+
+/**
+ * A CTA on a tier card. This is an EDUCATION/HANDOFF link only — it points at a
+ * tenant page (or the product-owned subscribe flow); the widget never renders a
+ * subscribe/checkout control of its own.
+ */
+export interface TierCta {
+  label: string;
+  href: string;
+}
+
+/**
+ * One membership/pricing tier (e.g. Guest, Member, Autopilot).
+ */
+export interface Tier {
+  /** Tier name, e.g. "Member". */
+  name: string;
+  /** One-line positioning under the name. */
+  tagline?: string;
+  /** Headline figure (price/savings). Illustrative unless `real` is set. */
+  figure?: TierFigure;
+  /** Feature bullets shown on the card. */
+  features?: TierFeature[];
+  /** Education/handoff CTA (never a checkout mechanic). */
+  cta?: TierCta;
+  /** Visually emphasize this tier as recommended. */
+  featured?: boolean;
+  /** Small ribbon text on a featured tier, e.g. "Most popular". */
+  badge?: string;
+  /**
+   * Assert this tier's figures are REAL, live values (opt out of the
+   * illustrative affordance). Default (undefined/false) → figures are treated
+   * as illustrative examples. Only set when the tenant confirms the numbers are
+   * an accurate live offer.
+   */
+  real?: boolean;
+}
+
+/**
+ * One row of the {@link TierComparisonTable} feature matrix. `cells` aligns to
+ * the table's `tiers` array by index: a boolean renders a check/dash, a string
+ * renders as text (e.g. "5 / mo"), and `null`/omitted renders an em dash.
+ */
+export interface ComparisonRow {
+  /** Row label (the feature/attribute compared across tiers). */
+  label: string;
+  /** Per-tier cell, aligned to the table's tiers by index. */
+  cells: Array<boolean | string | null>;
+}
+
+/**
+ * True when the widget should mark this tier's figures as illustrative. A tier
+ * that asserts `real: true` opts out; everything else is illustrative by
+ * default so example numbers are never shown as a live offer.
+ */
+export function isIllustrative(tier: Pick<Tier, "real">): boolean {
+  return tier.real !== true;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * In-memory KVNamespace for local dev. Lets the real KvTenantResolver + putTenant
+ * run under `astro dev` (where no Cloudflare KV binding exists) so the dynamic
+ * tenant path and a data-driven default are testable without a Cloudflare
+ * account. NOT used in production — the Workers runtime binds the real
+ * TENANT_CACHE namespace. Process-local and non-persistent by design.
+ */
+export class MemoryKv implements KVNamespace {
+  private readonly store = new Map<string, string>();
+
+  async get(key: string): Promise<string | null> {
+    return this.store.has(key) ? (this.store.get(key) as string) : null;
+  }
+
+  async put(key: string, value: string): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async list(
+    opts?: { prefix?: string; cursor?: string; limit?: number },
+  ): Promise<{ keys: { name: string }[]; list_complete: boolean; cursor?: string }> {
+    const prefix = opts?.prefix ?? "";
+    const keys = [...this.store.keys()]
+      .filter((k) => k.startsWith(prefix))
+      .map((name) => ({ name }));
+    return { keys, list_complete: true };
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}

package/apps/storefront/src/lib/messaging/messagesClient.ts

@@ -0,0 +1,143 @@
+/**
+ * MessagesClient — the storefront's seam to tot20's inline-body send (`POST /api/messages`).
+ *
+ * The storefront RENDERS its own branded email HTML and hands it to tot20 to TRANSMIT, so we
+ * reuse tot20's Mandrill SPF/DKIM deliverability (the whole point) while owning the body/brand.
+ * Used for the magic-link invite email (see lib/grants/magicLinkInvite.ts).
+ *
+ *   POST <core>/api/messages
+ *   { channel:"email", to, subject, html, totApiKey, totSecretKey }  → 200 { sent:true, id? }
+ *
+ * Creds go in the BODY (`totApiKey`/`totSecretKey`) — tot20's `normalizeSecureUserRequest`, same
+ * wire rule as the other operator clients. The storefront's operator key already holds
+ * `messaging:send`. DELIVERABILITY: do NOT set a non-`@tokenoftrust.com` From — omit it so the
+ * send stays SPF/DKIM-aligned with tot20's domain (a misaligned From lands in spam).
+ *
+ * Built like `@/lib/grants/developerInvites` (interface + Http impl + Mock + env factory).
+ */
+import { readEnv } from "@/lib/env";
+
+export interface InlineEmail {
+  /** Recipient address. */
+  to: string;
+  /** Subject line (your copy). */
+  subject: string;
+  /** Fully-rendered branded HTML body (your template). */
+  html: string;
+}
+
+export type MessageSendResult =
+  | { sent: true; id?: string }
+  | { sent: false; status: number; reason: string };
+
+export interface MessagesClient {
+  sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult>;
+}
+
+// --- HTTP transport seam (injected by tests) --------------------------------
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+export interface HttpTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+}
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    return fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+  }
+}
+
+export class MessagesClientError extends Error {}
+
+export interface HttpMessagesClientConfig {
+  baseUrl: string;
+  apiKey: string;
+  secretKey?: string;
+  transport?: HttpTransport;
+}
+
+export class HttpMessagesClient implements MessagesClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly secretKey?: string;
+  private readonly transport: HttpTransport;
+
+  constructor(config: HttpMessagesClientConfig) {
+    if (!config.baseUrl) throw new MessagesClientError("messages: TOT_CORE_URL is not configured");
+    if (!config.apiKey) throw new MessagesClientError("messages: storefront ToT credentials are not configured");
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.transport = config.transport ?? new FetchHttpTransport();
+  }
+
+  private credentialFields(): Record<string, string> {
+    const f: Record<string, string> = { totApiKey: this.apiKey };
+    if (this.secretKey) f.totSecretKey = this.secretKey;
+    return f;
+  }
+
+  async sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/messages`,
+        {},
+        {
+          channel: "email",
+          to: msg.to,
+          subject: msg.subject,
+          html: msg.html,
+          // No fromEmail/fromName → stays SPF/DKIM-aligned with tot20's domain (deliverability).
+          ...this.credentialFields(),
+        },
+      );
+    } catch (cause) {
+      return { sent: false, status: 0, reason: cause instanceof Error ? cause.message : String(cause) };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { sent: false, status: res.status, reason: `non-JSON body (status ${res.status})` };
+    }
+    return normalizeSend(res.status, body);
+  }
+}
+
+/** Parse tot20's `{ content, metadata }` send response into a typed result (fail closed). */
+export function normalizeSend(status: number, body: unknown): MessageSendResult {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const c = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+  if (c.sent === true || (status >= 200 && status < 300 && c.sent !== false)) {
+    return { sent: true, ...(typeof c.id === "string" ? { id: c.id } : {}) };
+  }
+  const reason =
+    typeof c.message === "string" ? c.message : typeof c.reason === "string" ? c.reason : `send failed (status ${status})`;
+  return { sent: false, status, reason };
+}
+
+// --- Mock (tests + local dev) -----------------------------------------------
+export class MockMessagesClient implements MessagesClient {
+  sent: InlineEmail[] = [];
+  constructor(private readonly result: MessageSendResult = { sent: true, id: "mock-msg" }) {}
+  async sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult> {
+    this.sent.push(msg);
+    return this.result;
+  }
+}
+
+// --- Factory ----------------------------------------------------------------
+export async function createMessagesClient(
+  overrides: Partial<HttpMessagesClientConfig> = {},
+): Promise<HttpMessagesClient> {
+  const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv("TOT_API_KEY")) ?? "";
+  const secretKey = overrides.secretKey ?? (await readEnv("TOT_SECRET_KEY"));
+  return new HttpMessagesClient({ ...overrides, baseUrl, apiKey, secretKey });
+}

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);
+}