@tokenoftrust/storefront-runner 1.3.2 → 1.3.4-rc.2

package/packages/public-runtime/src/checkout-style.ts

@@ -1,7 +1,7 @@
 /**
  * Checkout-styling data model + published-artifact read plumbing.
  *
- * The FoxyCart-hosted checkout is styled by CSS pushed to Foxy's `/theme/foxy`
+ * The hosted checkout is styled by CSS pushed through the commerce service's theme
  * endpoint (U11). This module owns the *source of truth* for that styling: a
  * small, structured, tenant-editable descriptor that later units render into
  * ASCII-safe CSS. It sits on the SAME versioned publish spine as theme/content
@@ -12,7 +12,7 @@
  * Two colocated artifacts under `tenants/<id>/`:
  *   - `checkout-style.json` — the structured `CheckoutStyle` descriptor (below).
  *   - `checkout.css`        — an optional raw-CSS escape hatch a merchant edits
- *                             directly; hosted + pushed to Foxy as-is (U11).
+ *                             directly; hosted + pushed to checkout as-is (U11).
  *
  * Pure + dependency-free (node-free, edge-safe): the caller injects the same
  * `KvGet` used for theme/content, keeping this unit-testable and storage-agnostic.
@@ -27,7 +27,7 @@ import { readPublishedArtifact, type KvGet } from "./customization-runtime.js";
  * subset of the full theme palette — the checkout is a focused conversion
  * surface, not the whole store. All values are CSS colors; hex is validated for
  * WCAG contrast downstream (U13 gate), non-hex (e.g. `rgb(...)`) is passed
- * through. Keep values ASCII-safe — Foxy's cache pass isn't Unicode-safe.
+ * through. Keep values ASCII-safe — the checkout cache pass isn't Unicode-safe.
  */
 export interface CheckoutStyleColors {
   /** Page background behind the checkout card. */
@@ -46,7 +46,7 @@ export interface CheckoutStyleColors {
 
 /**
  * Typography for the checkout page. `fontFamily` is a full CSS font-family stack
- * (a web-safe stack, or a Foxy-supported webfont name plus fallbacks) — kept as
+ * (a web-safe stack, or a provider-supported webfont name plus fallbacks) — kept as
  * an opaque string so a merchant can bring their own stack without a schema bump.
  */
 export interface CheckoutStyleTypography {
@@ -65,7 +65,7 @@ export interface CheckoutStyleButton {
 /**
  * The structured checkout-styling descriptor — the `checkout-style.json`
  * artifact. This is the model a merchant edits (U12) and that U11 renders into
- * the CSS pushed to Foxy. A published artifact is a `DeepPartial` of this
+ * the CSS pushed to checkout. A published artifact is a `DeepPartial` of this
  * (a merchant may set one field without restating the rest); `resolveCheckout
  * Style` merges it over `DEFAULT_CHECKOUT_STYLE` so the resolved value is always
  * complete.
@@ -114,12 +114,12 @@ export const DEFAULT_CHECKOUT_STYLE: CheckoutStyle = {
  *     stack (the checkout is body copy + a CTA, not display type)
  *   - button.radius ← `shape.radius.md` (the standard control radius)
  *   - logoUrl ← `brand.logoLight`, but ONLY when it is an absolute https URL —
- *     Foxy fetches the checkout server-side, so a repo-relative logo path
+ *     Checkout fetches the template server-side, so a repo-relative logo path
  *     (e.g. `/brand/logo.svg`) can't resolve there and is dropped.
  *
  * Input is a `DeepPartial` (a tenant's `theme.json` override is sparse), so every
  * field falls back to `DEFAULT_CHECKOUT_STYLE` when the theme omits it — the result
- * is always a complete `CheckoutStyle`. ASCII discipline (Foxy's cache is not
+ * is always a complete `CheckoutStyle`. ASCII discipline (the checkout cache is not
  * Unicode-safe): any derived string leaf that isn't `isAsciiSafe` is dropped in
  * favor of the default, so a theme can never produce a checkout-blanking value.
  * Pure + node-free.
@@ -193,7 +193,7 @@ export function checkoutStyleArtifactPath(tenantId: string): string {
 /**
  * Canonical path for the optional raw-CSS override artifact — the escape hatch a
  * merchant edits directly (or that advanced templates ship). Sibling to the
- * structured descriptor; hosted + pushed to Foxy verbatim by U11.
+ * structured descriptor; hosted + pushed to checkout verbatim by U11.
  */
 export function checkoutStyleCssPath(tenantId: string): string {
   return `tenants/${tenantId}/checkout.css`;
@@ -289,11 +289,11 @@ export async function resolveCheckoutStyleCss(
 }
 
 // ---------------------------------------------------------------------------
-// CSS serialization (the artifact pushed to FoxyCart) — U11
+// CSS serialization (the artifact pushed to checkout) — U11
 // ---------------------------------------------------------------------------
 
 /**
- * True iff every character is 7-bit ASCII (code point < 128). FoxyCart's
+ * True iff every character is 7-bit ASCII (code point < 128). The checkout
  * template cache pass is NOT Unicode-safe — a non-ASCII byte in the cached
  * checkout content yields a BLANK page. So the publisher (U11) MUST gate both
  * the generated token CSS and any raw override through this before pushing a
@@ -319,7 +319,7 @@ const CHECKOUT_COLOR_VARS: Record<keyof CheckoutStyleColors, string> = {
 
 /**
  * Serialize a resolved `CheckoutStyle` into a `:root { … }` block of CSS custom
- * properties (`--tot-checkout-*`) that a FoxyCart checkout template references.
+ * properties (`--tot-checkout-*`) that the hosted checkout template references.
  * Deterministic (stable key order) so an unchanged style produces byte-identical
  * output — the publisher can hash it to skip no-op pushes. The `logoUrl`, when
  * set, is emitted as `--tot-checkout-logo: url("…")`.
@@ -348,10 +348,10 @@ export function checkoutStyleToCss(style: CheckoutStyle): string {
 
 /**
  * Assemble the full checkout CSS served at the stable storefront URL that becomes
- * FoxyCart's `content_url`: the generated token block (`checkoutStyleToCss` over
+ * checkout's `content_url`: the generated token block (`checkoutStyleToCss` over
  * the resolved `CheckoutStyle`) followed by the tenant's optional raw-CSS override.
  *
- * ASCII discipline (Foxy's cache pass is not Unicode-safe → blank checkout): the
+ * ASCII discipline (the checkout cache pass is not Unicode-safe → blank checkout): the
  * raw override is appended ONLY when it is `isAsciiSafe` — a non-ASCII override is
  * DROPPED here so a bad byte can never blank the live checkout (the authoritative
  * reject-at-publish gate is U13's promote GateReport; this is defense-in-depth at

package/packages/public-runtime/src/{foxy.ts → checkout.ts}

@@ -1,35 +1,39 @@
 /**
- * FoxyCart cart engine — renderer-safe helpers (Track A).
+ * Managed checkout cart engine — renderer-safe helpers (Track A).
  *
- * The storefront's whole job as a FoxyCart front end is small: include Foxy's
- * loader.js, and emit add-to-cart links/forms whose product name/value pairs are
- * HMAC-signed with the store's "cart validation" secret so the price can't be
- * tampered. This module builds the fields for a catalog variant and (in signed
- * mode) signs them with WebCrypto HMAC-SHA256 — pure, dependency-free, and safe
- * in both `astro dev` (Node 20) and the Cloudflare Worker runtime.
+ * The storefront's job is intentionally small: include the managed checkout
+ * loader, and emit add-to-cart links/forms whose product name/value pairs are
+ * HMAC-signed with the store's cart-validation secret so the price can't be
+ * tampered with. This module builds the fields for a catalog variant and signs
+ * them with WebCrypto HMAC-SHA256 in signed mode — pure, dependency-free, and
+ * safe in both `astro dev` (Node 20) and the Cloudflare Worker runtime.
  *
- * The excise-tax line is NOT computed here — it materializes inside the FoxyCart
- * cart via the store's pre-cart webhook + `tot_excise_tax` coupon (Track B, the
- * tot-foxycart service). See docs / the excise-tax-checkout recipe.
+ * The excise-tax line is NOT computed here — it materializes inside the managed
+ * cart via the store's pre-cart webhook + `tot_excise_tax` coupon (Track B).
  *
- * Signing reference (Foxy "HMAC product verification"):
+ * Signing reference (checkout HMAC product verification):
  *   hash = HMAC-SHA256( productcode + fieldname + fieldvalue , storeSecret )
  *   link/form field name becomes `fieldname||hash` (value unchanged).
  *   Editable fields (quantity) hash the value `--OPEN--` and emit
  *   `fieldname||hash||open`. Cart-level params (cart, coupon, output, …) and
  *   `h:`/`x:`/`__`/`utm_`-prefixed params are never signed.
  */
-import type { CatalogProduct, CatalogVariant } from "./product.js";
+import type {
+  CatalogProduct,
+  CatalogVariant,
+  ProductPurchaseOption,
+  SubscriptionPurchaseOption,
+} from "./product.js";
 
 /**
- * Per-tenant FoxyCart wiring. Public config only — the signing SECRET is never
+ * Per-tenant managed-checkout wiring. Public config only — the signing SECRET is never
  * stored here (it's an env-injected Worker binding, resolved per request). In
  * `unsigned-demo` mode there is no secret at all: links go to a demo store that
  * has cart validation turned OFF, so a developer can run the full cart locally
  * (and on our shared preview worker) with zero secrets.
  */
-export interface FoxyCommerceConfig {
-  /** Foxy store subdomain, e.g. "tot-demo" → tot-demo.foxycart.com. */
+export interface ManagedCheckoutConfig {
+  /** Checkout store subdomain, e.g. "tot-demo". */
   storeSubDomain: string;
   /**
    * Full cart/checkout host. Defaults to `${storeSubDomain}.foxycart.com`; set
@@ -42,26 +46,25 @@ export interface FoxyCommerceConfig {
    */
   mode: "signed" | "unsigned-demo";
   /**
-   * Optional per-tenant CSS to brand Foxy's sidecart. Foxy's v2.0 sidecart
+   * Optional per-tenant CSS to brand the in-page cart drawer. The checkout loader
    * renders into our own page DOM (root `#fc`, light DOM — no iframe/shadow), so
    * it inherits the theme's CSS custom properties and can be restyled with plain
-   * CSS. `<FoxySidecartStyles>` already emits a brand baseline derived from the
+   * CSS. `<CartDrawerStyles>` already emits a brand baseline derived from the
    * theme tokens; this string is APPENDED after it for bespoke overrides. Scope
-   * every rule under `#fc` and use `!important` to beat Foxy's own
-   * responsive_styles.css (it loads after our <head> style). NB: this styles the
-   * in-page sidecart only — the hosted checkout page is a separate origin,
-   * themed in the Foxy admin template.
+   * every rule under `#fc` and use `!important` to beat the checkout loader's
+   * responsive styles. NB: this styles the in-page cart drawer only — the hosted
+   * checkout page is a separate origin, themed through checkout settings.
    */
-  sidecartCss?: string;
+  cartDrawerCss?: string;
 }
 
 /** Resolved, request-scoped commerce facts stashed on `Astro.locals`. */
-export interface ResolvedFoxyCommerce extends FoxyCommerceConfig {
+export interface ResolvedManagedCheckout extends ManagedCheckoutConfig {
   /** `https://<storeDomain>` — the loader + cart origin (for CSP + links). */
   origin: string;
   /** `https://<storeDomain>/cart` — the add-to-cart form action / cart link. */
   cartUrl: string;
-  /** `https://cdn.foxycart.com/<storeSubDomain>/loader.js`. */
+  /** Managed checkout loader script URL. */
   loaderSrc: string;
 }
 
@@ -88,14 +91,22 @@ export interface VariantCartPayload {
   quantityName: string;
 }
 
-const FOXY_HOST_SUFFIX = ".foxycart.com";
+export interface BuildVariantCartPayloadOptions {
+  mode: ManagedCheckoutConfig["mode"];
+  secret?: string;
+  purchaseOption?: ProductPurchaseOption;
+}
+
+const DEFAULT_CHECKOUT_HOST_SUFFIX = ".foxycart.com";
+const SUBSCRIPTION_FREQUENCY_RE = /^(?:\d+(?:\.\d+)?|\.\d+)[dwmy]$/;
 
 /** Resolve the full request-scoped commerce facts from a tenant's config. */
-export function resolveFoxyCommerce(
-  config: FoxyCommerceConfig,
-): ResolvedFoxyCommerce {
+export function resolveManagedCheckout(
+  config: ManagedCheckoutConfig,
+): ResolvedManagedCheckout {
   const storeDomain =
-    config.storeDomain ?? `${config.storeSubDomain}${FOXY_HOST_SUFFIX}`;
+    config.storeDomain ??
+    `${config.storeSubDomain}${DEFAULT_CHECKOUT_HOST_SUFFIX}`;
   const origin = `https://${storeDomain}`;
   return {
     ...config,
@@ -108,19 +119,21 @@ export function resolveFoxyCommerce(
 
 /**
  * The raw (unsigned) cart fields for a variant: name, price, code, image, the
- * variant's options, and an editable quantity. `code` is the Foxy "productcode"
+ * variant's options, and an editable quantity. `code` is the checkout product code
  * — the salt every other field is hashed against — so it must be stable per SKU.
  */
 export function cartFieldsForVariant(
   product: CatalogProduct,
   variant: CatalogVariant,
+  purchaseOption?: ProductPurchaseOption,
 ): { code: string; fields: CartField[] } {
   const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
     product.images[0]?.url;
+  const price = purchaseOptionPrice(variant.price, purchaseOption);
   const fields: CartField[] = [
     { name: "name", value: variant.title || product.title },
-    { name: "price", value: variant.price.toFixed(2) },
+    { name: "price", value: price.toFixed(2) },
     { name: "code", value: code },
     { name: "quantity", value: "1", open: true },
   ];
@@ -130,9 +143,69 @@ export function cartFieldsForVariant(
   for (const [optName, optVal] of Object.entries(variant.option_values)) {
     if (optName && optVal) fields.push({ name: optName, value: optVal });
   }
+  if (purchaseOption?.kind === "subscription") {
+    fields.push(...subscriptionCartFields(purchaseOption));
+  }
   return { code, fields };
 }
 
+export function purchaseOptionPrice(
+  basePrice: number,
+  purchaseOption?: ProductPurchaseOption,
+): number {
+  if (purchaseOption?.kind !== "subscription") return basePrice;
+  const adjustment = purchaseOption.priceAdjustment;
+  if (!adjustment) return basePrice;
+  if (!Number.isFinite(adjustment.value) || adjustment.value < 0) {
+    throw new Error(
+      `purchase option "${purchaseOption.id}" has invalid price adjustment`,
+    );
+  }
+  if (adjustment.type === "percent_off" && adjustment.value > 100) {
+    throw new Error(
+      `purchase option "${purchaseOption.id}" has invalid percent discount`,
+    );
+  }
+  if (adjustment.type === "amount_off" && adjustment.value > basePrice) {
+    throw new Error(
+      `purchase option "${purchaseOption.id}" has invalid amount discount`,
+    );
+  }
+  const adjusted =
+    adjustment.type === "percent_off"
+      ? basePrice * (1 - adjustment.value / 100)
+      : basePrice - adjustment.value;
+  return Number(adjusted.toFixed(2));
+}
+
+export function isSubscriptionFrequency(value: string): boolean {
+  if (!SUBSCRIPTION_FREQUENCY_RE.test(value)) return false;
+  const amount = Number.parseFloat(value.slice(0, -1));
+  return Number.isFinite(amount) && amount > 0;
+}
+
+function subscriptionCartFields(
+  option: SubscriptionPurchaseOption,
+): CartField[] {
+  if (!isSubscriptionFrequency(option.frequency)) {
+    throw new Error(
+      `subscription purchase option "${option.id}" has invalid frequency "${option.frequency}"`,
+    );
+  }
+
+  const fields: CartField[] = [
+    { name: "Purchase option", value: option.label },
+    { name: "sub_frequency", value: option.frequency },
+  ];
+  if (option.startDate) {
+    fields.push({ name: "sub_startdate", value: option.startDate });
+  }
+  if (option.endDate) {
+    fields.push({ name: "sub_enddate", value: option.endDate });
+  }
+  return fields;
+}
+
 /** Lowercase hex HMAC-SHA256(message) under `secret`, via WebCrypto. */
 async function hmacHex(secret: string, message: string): Promise<string> {
   const enc = new TextEncoder();
@@ -151,7 +224,7 @@ async function hmacHex(secret: string, message: string): Promise<string> {
 
 /**
  * Sign one field for product `code`. Editable fields hash the sentinel
- * `--OPEN--` and gain the `||open` suffix so Foxy accepts a user-entered value.
+ * `--OPEN--` and gain the `||open` suffix so checkout accepts a user-entered value.
  */
 async function signField(
   secret: string,
@@ -174,9 +247,13 @@ async function signField(
 export async function buildVariantCartPayload(
   product: CatalogProduct,
   variant: CatalogVariant,
-  opts: { mode: FoxyCommerceConfig["mode"]; secret?: string },
+  opts: BuildVariantCartPayloadOptions,
 ): Promise<VariantCartPayload> {
-  const { code, fields } = cartFieldsForVariant(product, variant);
+  const { code, fields } = cartFieldsForVariant(
+    product,
+    variant,
+    opts.purchaseOption,
+  );
   const signed = opts.mode === "signed";
   if (signed && !opts.secret) {
     throw new Error(

package/packages/public-runtime/src/csp.ts

@@ -22,8 +22,8 @@ export interface CspOptions {
   /** Sandboxed-widget origins. */
   frameSrc?: readonly string[];
   /**
-   * Extra `form-action` targets. Default is `'self'`; the FoxyCart add-to-cart
-   * form POSTs cross-origin to the store's `/cart`, so that origin is added here.
+   * Extra `form-action` targets. Default is `'self'`; add-to-cart forms POST
+   * cross-origin to the checkout store's `/cart`, so that origin is added here.
    */
   formAction?: readonly string[];
   /** Reporting group name for `report-to` (paired with a Reporting-Endpoints header). */
@@ -78,13 +78,13 @@ export const STOREFRONT_CSP_ALLOWLIST = {
 } as const;
 
 /**
- * CSP additions for a FoxyCart-enabled tenant. The loader.js comes from
- * `cdn.foxycart.com`; the sidecart XHR + iframe + the add-to-cart form POST all
- * hit the store's own origin (`<store>.foxycart.com` or a branded checkout
- * domain). Merge these into `buildCsp` per request when `locals.commerce.foxy`
- * is present so the strict policy still passes.
+ * CSP additions for a managed-checkout tenant. The loader comes from the checkout
+ * CDN; cart requests, frames, and add-to-cart form POSTs hit the store's own
+ * origin (`<store>.foxycart.com` or a branded checkout domain). Merge these into
+ * `buildCsp` per request when `locals.commerce` is present so the strict policy
+ * still passes.
  */
-export function foxyCspAdditions(storeOrigin: string): {
+export function checkoutCspAdditions(storeOrigin: string): {
   scriptSrc: string[];
   styleSrc: string[];
   fontSrc: string[];
@@ -94,9 +94,9 @@ export function foxyCspAdditions(storeOrigin: string): {
   imgSrc: string[];
 } {
   const cdn = "https://cdn.foxycart.com";
-  // Foxy's loader pulls its own JS, CSS, and fonts from the CDN and renders the
-  // sidecart/checkout from the store origin — so it needs script/style/font from
-  // the CDN and connect/frame/form to the store.
+  // The checkout loader pulls its own JS, CSS, and fonts from the CDN and renders
+  // cart/checkout from the store origin, so it needs script/style/font from the
+  // CDN and connect/frame/form to the store.
   return {
     scriptSrc: [cdn, storeOrigin],
     styleSrc: [cdn, storeOrigin],

package/packages/public-runtime/src/customization-scripts.ts

@@ -18,6 +18,34 @@ export type ScriptSlot = (typeof SCRIPT_SLOTS)[number];
 export type ScriptStrategy = (typeof SCRIPT_STRATEGIES)[number];
 export type ScriptIsolation = (typeof SCRIPT_ISOLATIONS)[number];
 
+export interface ScriptSlotDescriptor {
+  slot: ScriptSlot;
+  label: string;
+  description: string;
+  defaultStrategy: ScriptStrategy;
+}
+
+export const SCRIPT_SLOT_DESCRIPTORS: Record<ScriptSlot, ScriptSlotDescriptor> = {
+  "product.aside": {
+    slot: "product.aside",
+    label: "Product Aside",
+    description: "A sandboxed widget beside product purchase controls.",
+    defaultStrategy: "on-interaction",
+  },
+  "home.section": {
+    slot: "home.section",
+    label: "Home Section",
+    description: "A sandboxed widget between composed homepage sections.",
+    defaultStrategy: "on-idle",
+  },
+  "global.footer": {
+    slot: "global.footer",
+    label: "Global Footer",
+    description: "A sandboxed widget near the page footer on every route.",
+    defaultStrategy: "defer",
+  },
+};
+
 export interface ScriptRegistration {
   src: string;
   slot: ScriptSlot;

package/packages/public-runtime/src/extension-contract.ts

@@ -0,0 +1,73 @@
+/**
+ * Public storefront extension contract.
+ *
+ * Astro components remain platform-owned implementation detail; tenants compose
+ * with versioned JSON blocks and sources. This file is renderer-safe and can be
+ * used by docs, validators, CLI checks, and the storefront app itself.
+ */
+
+export const BLOCK_PALETTE_CURRENT_CONTRACT = "block-palette@3" as const;
+export const BLOCK_PALETTE_SUPPORTED_CONTRACTS = [
+  "block-palette@1",
+  "block-palette@2",
+  BLOCK_PALETTE_CURRENT_CONTRACT,
+] as const;
+
+export type BlockPaletteContract =
+  (typeof BLOCK_PALETTE_SUPPORTED_CONTRACTS)[number];
+
+export const FEATURED_PRODUCT_SOURCE_KEYS = [
+  "featured",
+  "newest",
+  "bestSelling",
+  "onSale",
+] as const;
+
+export type FeaturedProductSourceKey =
+  (typeof FEATURED_PRODUCT_SOURCE_KEYS)[number];
+
+export type ProductSectionSource =
+  | FeaturedProductSourceKey
+  | { collection: string }
+  | { tag: string }
+  | { featured: true }
+  | { newest: true }
+  | { bestSelling: true }
+  | { onSale: true }
+  | { handles: string[] }
+  | { related: string }
+  | { recentlyViewed: true };
+
+export function isFeaturedProductSourceKey(
+  value: unknown,
+): value is FeaturedProductSourceKey {
+  return (
+    typeof value === "string" &&
+    (FEATURED_PRODUCT_SOURCE_KEYS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Normalize the authored shortcut syntax into the object shape consumed by
+ * section renderers. `handles` is accepted as a backwards-compatible sibling
+ * prop for existing `featured_products` blocks.
+ */
+export function normalizeProductSectionSource(
+  source?: ProductSectionSource,
+  handles?: string[],
+): Exclude<ProductSectionSource, FeaturedProductSourceKey> {
+  if (handles?.length) return { handles };
+  if (!source) return { featured: true };
+  if (typeof source !== "string") return source;
+  switch (source) {
+    case "newest":
+      return { newest: true };
+    case "bestSelling":
+      return { bestSelling: true };
+    case "onSale":
+      return { onSale: true };
+    case "featured":
+    default:
+      return { featured: true };
+  }
+}

package/packages/public-runtime/src/index.ts

@@ -15,8 +15,8 @@
 // preview / script types the renderer needs. Read/apply only.
 export * from "./product.js";
 export * from "./tenant.js";
-export * from "./foxy.js";
-export * from "./foxy-orders.js";
+export * from "./checkout.js";
+export * from "./checkout-orders.js";
 export * from "./capabilities.js";
 export * from "./checkout-style.js";
 export * from "./checkout-style-publish.js";
@@ -29,6 +29,8 @@ export * from "./customization-runtime.js";
 export * from "./customization-versioning.js";
 export * from "./customization-scripts.js";
 export * from "./customization-reconcile.js";
+export * from "./extension-contract.js";
+export * from "./raw-html-policy.js";
 export * from "./tenant-assets.js";
 export * from "./binary-path.js";
 export * from "./hot-standby-readiness.js";

package/packages/public-runtime/src/product.ts

@@ -43,6 +43,49 @@ export interface ProductOption {
   values: string[];
 }
 
+export type PurchaseOptionKind = "one_time" | "subscription";
+
+export interface OneTimePurchaseOption {
+  id: string;
+  kind: "one_time";
+  label: string;
+  description?: string;
+}
+
+export type PurchaseOptionPriceAdjustment =
+  | { type: "percent_off"; value: number }
+  | { type: "amount_off"; value: number };
+
+export interface SubscriptionPurchaseOption {
+  id: string;
+  kind: "subscription";
+  label: string;
+  description?: string;
+  /** Shopper-facing savings copy, e.g. "Save 15%". Display only. */
+  savingsLabel?: string;
+  /** Optional signed-cart price adjustment, e.g. 15% off every recurring order. */
+  priceAdjustment?: PurchaseOptionPriceAdjustment;
+  /**
+   * Recurrence interval accepted by the checkout engine, e.g. "2w", "1m",
+   * "60d", "1y", ".5m".
+   */
+  frequency: string;
+  /** Optional future start/free-trial date or fixed renewal day. */
+  startDate?: string;
+  /** Optional subscription/payment-plan stop date. */
+  endDate?: string;
+}
+
+export type ProductPurchaseOption =
+  | OneTimePurchaseOption
+  | SubscriptionPurchaseOption;
+
+export const DEFAULT_ONE_TIME_PURCHASE_OPTION: OneTimePurchaseOption = {
+  id: "one_time",
+  kind: "one_time",
+  label: "One-time purchase",
+};
+
 export interface CatalogImage {
   id: string;
   /** Final URL after rehost (R2/Cloudflare Images) OR original Shopify CDN URL. */
@@ -111,6 +154,12 @@ export interface CatalogProduct {
   options: ProductOption[];
   images: CatalogImage[];
   variants: CatalogVariant[];
+  /**
+   * Optional purchase modes for this product. Omitted/empty means a standard
+   * one-time purchase. Subscription options are authored as catalog data; the
+   * storefront converts them into provider-specific cart parameters at render.
+   */
+  purchase_options?: ProductPurchaseOption[];
   price_range: PriceRange;
   /** Collection handles (or ids) this product belongs to. */
   collections: string[];
@@ -122,6 +171,14 @@ export interface CatalogProduct {
   source_checksum: string;
 }
 
+export function normalizePurchaseOptions(
+  product: Pick<CatalogProduct, "purchase_options">,
+): ProductPurchaseOption[] {
+  return product.purchase_options?.length
+    ? product.purchase_options
+    : [DEFAULT_ONE_TIME_PURCHASE_OPTION];
+}
+
 /**
  * A product review (full content), pulled from the merchant's reviews app
  * (e.g. Stamped.io public widget API) during migration. The aggregate

package/packages/public-runtime/src/raw-html-policy.ts

@@ -0,0 +1,35 @@
+/**
+ * Policy for the raw tenant-authored HTML path.
+ *
+ * Raw HTML is a useful migration/marketing bridge, but it bypasses Astro Layout
+ * composition. Regulated tenants must stay on a platform-composed path
+ * so age/identity verification, warnings, taxes, checkout signing, and publish
+ * gates remain non-removable.
+ */
+import type { TenantConfig } from "./tenant.js";
+import { resolveComplianceObligations } from "./capabilities.js";
+
+export interface RawHtmlPolicyDecision {
+  allowed: boolean;
+  regulated: boolean;
+  reason?: string;
+}
+
+export function rawHtmlPolicy(
+  tenant: Pick<TenantConfig, "siteType" | "compliance">,
+): RawHtmlPolicyDecision {
+  const obligations = resolveComplianceObligations(tenant);
+  const regulated =
+    obligations.ageVerification.required || obligations.exciseTax.required;
+
+  if (regulated) {
+    return {
+      allowed: false,
+      regulated,
+      reason:
+        "Raw HTML bypasses platform Layout compliance; regulated commerce tenants must use block composition or an extracted runtime.",
+    };
+  }
+
+  return { allowed: true, regulated };
+}