@tribe-nest/forge 3.14.0 → 3.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.14.0",
+  "version": "3.17.0",
   "publishConfig": {
     "access": "public"
   },

package/src/contexts/CartContext.tsx

@@ -29,7 +29,22 @@ export type CartItem = {
   quantity: number;
   recipientMessage?: string;
   payWhatYouWant: boolean;
+  /**
+   * WHICH version this line is — "Format: FLAC", "Size: L".
+   *
+   * The cart used to show a colour swatch and a size string, which is all a
+   * variant could be. Anything else was unnameable: a buyer who chose FLAC over
+   * MP3 saw two identical lines at two prices and no way to tell which was
+   * which, right at the moment they are deciding whether to pay.
+   *
+   * Optional because a product sold one way has no versions to distinguish, and
+   * because carts persist — a line saved before this existed still has to
+   * render.
+   */
+  options?: { axis: string; value: string; swatchHex?: string | null }[];
+  /** @deprecated Superseded by `options`. Still read for carts saved earlier. */
   color?: string;
+  /** @deprecated Superseded by `options`. Still read for carts saved earlier. */
   size?: string;
   /**
    * REQUIRED, and deliberately so.
@@ -67,7 +82,16 @@ export type TicketCartItem = {
   /** ticketId → quantity, matching `useEventCheckout`'s `selectedTickets`. */
   tickets: Record<string, number>;
   /** Display data per ticket id, so the cart can render lines without refetching. */
-  ticketMeta: Record<string, { title: string; price: number }>;
+  /**
+   * `price` is the per-unit figure the cart DISPLAYS — on a pay-what-you-want
+   * tier that is the buyer's chosen amount, not the tier's floor, so returning
+   * from an add-on page doesn't silently forget what they picked.
+   *
+   * `pwywAmount` is the same number carried explicitly, because the bundle
+   * endpoint treats a line's `price` as display-only and never charges it; the
+   * chosen amount has to arrive in a field the server actually reads.
+   */
+  ticketMeta: Record<string, { title: string; price: number; pwywAmount?: number }>;
 };
 
 interface CartContextType {

package/src/data/queries/useCheckouts.ts

@@ -25,7 +25,14 @@ export type CheckoutLineInput =
       eventId: string;
       ticketId: string;
       quantity: number;
+      /** Display only — the bundle never charges this. */
       price: number;
+      /**
+       * The buyer's chosen per-unit amount on a pay-what-you-want tier. Unlike
+       * `price`, this IS forwarded into the ticket order and charged (after the
+       * server clamps it against the tier's floor).
+       */
+      pwywAmount?: number;
       title: string;
       coverImage?: string;
     };
@@ -45,6 +52,13 @@ export function cartToCheckoutLines(cartItems: CartItem[], ticketItems: TicketCa
         ticketId,
         quantity: qty,
         price: t.ticketMeta[ticketId]?.price ?? 0,
+        // Sent SEPARATELY from `price` above, which the bundle treats as
+        // display-only and never charges. This is the field the server forwards
+        // into the ticket order — dropping it would charge the tier's floor and
+        // still return 200, so the buyer would be quietly undercharged.
+        ...(t.ticketMeta[ticketId]?.pwywAmount != null
+          ? { pwywAmount: t.ticketMeta[ticketId]?.pwywAmount }
+          : {}),
         title: t.ticketMeta[ticketId]?.title ?? t.eventTitle,
         coverImage: t.coverImage,
       })),

package/src/data/queries/useEvents.ts

@@ -43,6 +43,12 @@ export function useEvent(id?: string, options?: { initialData?: IEvent }) {
 
 export type CreateEventOrderInput = {
   items: Record<string, number>;
+  /**
+   * ticketId → the buyer's chosen amount, PER UNIT, on a pay-what-you-want
+   * tier. Ignored server-side for any tier that is not PWYW, and clamped up to
+   * the tier's own `price` — it can raise what is charged, never lower it.
+   */
+  amounts?: Record<string, number>;
   email: string;
   firstName?: string;
   lastName?: string;

package/src/index.ts

@@ -30,6 +30,9 @@ export { CartProvider, useCart } from "./contexts/CartContext";
 // way the cart and audio player are — so a code site and a Craft site cannot
 // disagree about which version a buyer picked.
 export { useVariantSelection } from "./ui/headless/useVariantSelection";
+// Which version a cart line is. Exported from the package root because the
+// Craft themes render their own cart and must resolve it the same way.
+export { resolveCartLineOptions } from "./ui/styled/CartLineOptions";
 export type { VariantAxis, VariantAxisValue } from "./ui/headless/useVariantSelection";
 export type { CartItem, TicketCartItem, AttachedTo } from "./contexts/CartContext";
 export {

package/src/types/models.ts

@@ -582,6 +582,15 @@ export type IMedia = {
   type: MediaType;
   previewUrl?: string | null;
   previewStatus?: string | null;
+  /**
+   * Which version this file is for, when it is a song's file.
+   *
+   * Null — and absent everywhere else — means every version gets it. Present so
+   * an EDITOR can round-trip a per-version file; a storefront never needs it,
+   * because the server has already filtered the list to the version being
+   * viewed.
+   */
+  productOptionValueId?: string | null;
 };
 
 /**
@@ -1097,11 +1106,22 @@ export type ITicket = {
   id: string;
   title: string;
   description: string;
+  /**
+   * On a pay-what-you-want tier this is the MINIMUM, not a fixed price — there
+   * is no separate minimum field. Every "from $X" on the storefront reads it,
+   * which is exactly why it stays the floor.
+   */
   price: number;
   // Optional display-only "compare-at" price (higher than `price`). When
   // present the storefront strikes it through next to `price`. Charging uses
-  // `price`.
+  // `price`. Mutually exclusive with `payWhatYouWant` — the API refuses both.
   compareAtPrice?: number | string | null;
+  /** Buyer chooses the amount, at or above `price`. */
+  payWhatYouWant?: boolean;
+  /** Pre-fills the buyer's amount box. Presentation only — never a floor. */
+  pwywSuggestedAmount?: number | string | null;
+  /** Enforced server-side at checkout. */
+  payWhatYouWantMaximum?: number | string | null;
   quantity: number;
   order: number;
   sold: number;
@@ -1268,7 +1288,20 @@ export type IPublicOrderItem = {
   quantity: number;
   recipientMessage?: string;
   payWhatYouWant: boolean;
+  /**
+   * What this line WAS, recorded when it was sold.
+   *
+   * Not resolved through `productVariantId` on read: the creator can rename an
+   * option value or delete the version, and an order that re-resolves would
+   * quietly start describing itself differently from how it was bought.
+   *
+   * Null for a product sold one way, and for every order placed before the
+   * snapshot existed — those fall back to `size` below.
+   */
+  variantOptions?: { axis: string; value: string; swatchHex?: string | null }[] | null;
+  /** @deprecated Superseded by `variantOptions`. The only record for older orders. */
   color: string;
+  /** @deprecated Superseded by `variantOptions`. The only record for older orders. */
   size: string;
 };
 

package/src/ui/format/_tests/pwyw.spec.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect } from "vitest";
+import type { ITicket } from "../../../types/models";
+import {
+  clampChosenAmount,
+  isPayWhatYouWant,
+  pwywDefaultAmount,
+  pwywMaximum,
+  resolveUnitPrice,
+  ticketSubtotals,
+} from "../pwyw";
+
+/**
+ * The pay-what-you-want arithmetic shared by BOTH storefront stacks (Forge and
+ * the legacy client). It is shared rather than written twice precisely so the
+ * two cannot drift from each other or from the server — these tests pin the
+ * behaviour they both depend on.
+ *
+ * The clamp here is UX, not enforcement: the server clamps again and is what
+ * decides the charge. What matters is that the number on screen matches the
+ * number that will be charged.
+ */
+
+const tier = (over: Partial<ITicket> = {}): ITicket => ({
+  id: over.id ?? "t1",
+  title: "GA",
+  description: "",
+  price: 20,
+  quantity: 100,
+  order: 0,
+  sold: 0,
+  maxPerPerson: 10,
+  ...over,
+});
+
+describe("pwyw helpers", () => {
+  describe("isPayWhatYouWant", () => {
+    it("is false when the flag is absent — every pre-feature tier", () => {
+      expect(isPayWhatYouWant(tier())).toBe(false);
+    });
+
+    it("is true only when explicitly set", () => {
+      expect(isPayWhatYouWant(tier({ payWhatYouWant: true }))).toBe(true);
+    });
+  });
+
+  describe("pwywMaximum", () => {
+    it("is null on a non-PWYW tier even if a maximum is stored", () => {
+      // A stale ceiling on a tier whose toggle was turned off must not start
+      // constraining a fixed price.
+      expect(pwywMaximum(tier({ payWhatYouWantMaximum: 50 }))).toBeNull();
+    });
+
+    it("parses a numeric string, as the API returns for decimals", () => {
+      expect(pwywMaximum(tier({ payWhatYouWant: true, payWhatYouWantMaximum: "50.00" }))).toBe(50);
+    });
+
+    it("is null for an unparseable value rather than NaN", () => {
+      expect(pwywMaximum(tier({ payWhatYouWant: true, payWhatYouWantMaximum: "nonsense" }))).toBeNull();
+    });
+  });
+
+  describe("pwywDefaultAmount", () => {
+    it("falls back to the floor with no suggestion", () => {
+      expect(pwywDefaultAmount(tier({ payWhatYouWant: true }))).toBe(20);
+    });
+
+    it("uses the operator's suggestion", () => {
+      expect(pwywDefaultAmount(tier({ payWhatYouWant: true, pwywSuggestedAmount: 35 }))).toBe(35);
+    });
+
+    it("never pre-fills below the floor", () => {
+      // Otherwise the form opens with a value its own validation rejects.
+      expect(pwywDefaultAmount(tier({ payWhatYouWant: true, pwywSuggestedAmount: 5 }))).toBe(20);
+    });
+
+    it("never pre-fills above the maximum", () => {
+      expect(
+        pwywDefaultAmount(tier({ payWhatYouWant: true, pwywSuggestedAmount: 80, payWhatYouWantMaximum: 50 })),
+      ).toBe(50);
+    });
+  });
+
+  describe("clampChosenAmount", () => {
+    const t = tier({ payWhatYouWant: true });
+
+    it("keeps a figure above the floor", () => {
+      expect(clampChosenAmount(t, 75)).toBe(75);
+    });
+
+    it("raises a figure below the floor — the one-directional property", () => {
+      expect(clampChosenAmount(t, 1)).toBe(20);
+    });
+
+    it.each([
+      ["null", null],
+      ["undefined", undefined],
+      ["NaN", NaN],
+      ["negative", -50],
+      ["zero", 0],
+    ])("falls back to the floor for %s", (_label, value) => {
+      expect(clampChosenAmount(t, value as number | null | undefined)).toBe(20);
+    });
+
+    it("caps at the maximum", () => {
+      expect(clampChosenAmount(tier({ payWhatYouWant: true, payWhatYouWantMaximum: 50 }), 5000)).toBe(50);
+    });
+  });
+
+  describe("resolveUnitPrice", () => {
+    it("ignores a chosen amount on a non-PWYW tier, matching the server", () => {
+      expect(resolveUnitPrice(tier(), 500)).toBe(20);
+      expect(resolveUnitPrice(tier(), 1)).toBe(20);
+    });
+
+    it("honours a chosen amount on a PWYW tier", () => {
+      expect(resolveUnitPrice(tier({ payWhatYouWant: true }), 75)).toBe(75);
+    });
+  });
+
+  describe("ticketSubtotals", () => {
+    it("returns identical paid and floor figures with no PWYW tier", () => {
+      // The property that makes every existing surface's numbers unchanged.
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 20 }), tier({ id: "b", price: 30 })],
+        quantities: { a: 2, b: 1 },
+      });
+      expect(result).toEqual({ paid: 70, floor: 70 });
+    });
+
+    it("separates what is paid from what the fee is computed on", () => {
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 20, payWhatYouWant: true })],
+        quantities: { a: 2 },
+        amounts: { a: 75 },
+      });
+      expect(result).toEqual({ paid: 150, floor: 40 });
+    });
+
+    it("mixes PWYW and fixed tiers correctly", () => {
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 10, payWhatYouWant: true }), tier({ id: "b", price: 40 })],
+        quantities: { a: 2, b: 1 },
+        amounts: { a: 35 },
+      });
+      expect(result).toEqual({ paid: 110, floor: 60 });
+    });
+
+    it("ignores tiers with no quantity selected", () => {
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 20, payWhatYouWant: true })],
+        quantities: {},
+        amounts: { a: 500 },
+      });
+      expect(result).toEqual({ paid: 0, floor: 0 });
+    });
+  });
+});

package/src/ui/format/pwyw.ts

@@ -0,0 +1,95 @@
+import type { ITicket } from "../../types/models";
+
+/**
+ * Pay-what-you-want, as a buyer-facing surface has to handle it.
+ *
+ * ## The floor is the ticket, everything above it is a tip
+ *
+ * On a PWYW tier `ticket.price` IS the minimum — there is no separate minimum
+ * field — so every existing "from $X" already reads the right number. What
+ * changes is that the buyer may choose to pay MORE, and two totals then exist
+ * at once:
+ *
+ *  - the **paid** subtotal, which is what the card is charged, and
+ *  - the **floor** subtotal, which is what discounts and the artist's booking
+ *    fee are calculated on.
+ *
+ * The server computes both the same way (`PublicEventsService.createOrder`).
+ * These helpers exist so a storefront cannot accidentally show a fee estimate
+ * derived from the paid figure and then be charged one derived from the floor.
+ *
+ * ## The client is not the guard
+ *
+ * `clampChosenAmount` is UX, not enforcement. The server reads the PWYW flag
+ * off the ticket row and refuses anything below `price` regardless of what a
+ * client sends — a buyer cannot pay less than the floor by editing anything
+ * here. The clamp exists so the number on screen is the number that will be
+ * charged, not to make the request safe.
+ */
+
+const toNumber = (value: number | string | null | undefined): number | null => {
+  if (value == null) return null;
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+export const isPayWhatYouWant = (ticket: ITicket): boolean => !!ticket.payWhatYouWant;
+
+/** The tier's ceiling, or `null` for no limit. */
+export const pwywMaximum = (ticket: ITicket): number | null =>
+  isPayWhatYouWant(ticket) ? toNumber(ticket.payWhatYouWantMaximum) : null;
+
+/**
+ * What the amount box should start at: the operator's suggestion when there is
+ * one, else the floor. Never below the floor — a suggestion under the minimum
+ * would pre-fill the form with a value the buyer is not allowed to pay.
+ */
+export const pwywDefaultAmount = (ticket: ITicket): number => {
+  const floor = ticket.price;
+  const suggested = toNumber(ticket.pwywSuggestedAmount);
+  if (suggested == null || suggested < floor) return floor;
+  const maximum = pwywMaximum(ticket);
+  return maximum != null ? Math.min(suggested, maximum) : suggested;
+};
+
+/** Pin a buyer-entered figure into [floor, maximum]. Mirrors the server clamp. */
+export const clampChosenAmount = (ticket: ITicket, chosen: number | null | undefined): number => {
+  const floor = ticket.price;
+  if (chosen == null || !Number.isFinite(chosen) || chosen < floor) return floor;
+  const maximum = pwywMaximum(ticket);
+  return maximum != null ? Math.min(chosen, maximum) : chosen;
+};
+
+/**
+ * The per-unit price this tier will actually be charged at.
+ *
+ * A non-PWYW tier ignores `chosen` entirely, exactly as the server does — so a
+ * stale amount left in state after the operator turns PWYW off cannot change
+ * what is shown.
+ */
+export const resolveUnitPrice = (ticket: ITicket, chosen: number | null | undefined): number =>
+  isPayWhatYouWant(ticket) ? clampChosenAmount(ticket, chosen) : ticket.price;
+
+/**
+ * Both subtotals for a selection, in one pass.
+ *
+ * `paid` is what the buyer owes for the tickets; `floor` is the base the
+ * booking-fee estimate and any percentage discount must be computed against.
+ * They are equal on any cart with no PWYW tier, which is why every existing
+ * surface keeps its current numbers untouched.
+ */
+export function ticketSubtotals(input: {
+  tickets: ITicket[];
+  quantities: Record<string, number>;
+  amounts?: Record<string, number>;
+}): { paid: number; floor: number } {
+  let paid = 0;
+  let floor = 0;
+  for (const ticket of input.tickets) {
+    const quantity = input.quantities[ticket.id] ?? 0;
+    if (quantity <= 0) continue;
+    paid += resolveUnitPrice(ticket, input.amounts?.[ticket.id]) * quantity;
+    floor += ticket.price * quantity;
+  }
+  return { paid, floor };
+}

package/src/ui/headless/event/useEventCheckout.ts

@@ -5,6 +5,7 @@ import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField } from "../coupon/useCouponField";
 import { computeBookingFeeAmount } from "../../format/bookingFee";
+import { isPayWhatYouWant, pwywDefaultAmount, resolveUnitPrice, ticketSubtotals } from "../../format/pwyw";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -42,6 +43,12 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
 
   const [step, setStep] = useState<EventCheckoutStep>("tickets");
   const [selectedTickets, setSelectedTickets] = useState<Record<string, number>>({});
+  /**
+   * ticketId → the amount the buyer chose, per unit, on a pay-what-you-want
+   * tier. Absent means "hasn't touched the box", which resolves to the tier's
+   * suggested amount (or its floor) rather than to zero.
+   */
+  const [pwywAmounts, setPwywAmounts] = useState<Record<string, number>>({});
   const [firstName, setFirstName] = useState(user?.firstName ?? "");
   const [lastName, setLastName] = useState(user?.lastName ?? "");
   const [email, setEmail] = useState(user?.email ?? "");
@@ -70,10 +77,39 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
    */
   const coupon = useCouponField();
 
-  const totalAmount = useMemo(() => {
-    if (!event) return 0;
-    return event.tickets.reduce((sum, t) => sum + t.price * (selectedTickets[t.id] ?? 0), 0);
-  }, [event, selectedTickets]);
+  /**
+   * The buyer's effective per-unit choice for every selected PWYW tier —
+   * their typed figure where they have one, the tier's suggested amount where
+   * they have not. This is what gets SENT, so an untouched box is not the same
+   * as choosing the minimum: the suggestion is the default offer.
+   */
+  const effectiveAmounts = useMemo(() => {
+    if (!event) return {} as Record<string, number>;
+    const out: Record<string, number> = {};
+    for (const ticket of event.tickets) {
+      if (!isPayWhatYouWant(ticket) || (selectedTickets[ticket.id] ?? 0) <= 0) continue;
+      out[ticket.id] =
+        pwywAmounts[ticket.id] != null
+          ? resolveUnitPrice(ticket, pwywAmounts[ticket.id])
+          : pwywDefaultAmount(ticket);
+    }
+    return out;
+  }, [event, selectedTickets, pwywAmounts]);
+
+  /**
+   * `paid` is what the buyer owes for tickets; `floor` is the same cart valued
+   * at every tier's minimum. Identical on any cart without a PWYW tier.
+   */
+  const subtotals = useMemo(() => {
+    if (!event) return { paid: 0, floor: 0 };
+    return ticketSubtotals({
+      tickets: event.tickets,
+      quantities: selectedTickets,
+      amounts: effectiveAmounts,
+    });
+  }, [event, selectedTickets, effectiveAmounts]);
+
+  const totalAmount = subtotals.paid;
 
   const ticketCount = useMemo(
     () => Object.values(selectedTickets).reduce((a, b) => a + b, 0),
@@ -100,8 +136,13 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
    * honest while the buyer is still choosing quantities, which is precisely when
    * the disclosure has to happen.
    */
+  //
+  // Estimated off the FLOOR subtotal, never the paid one — the server computes
+  // it that way, so a fan choosing to pay ten times the minimum must not see
+  // (or be quoted) ten times the fee. On a cart with no PWYW tier the two
+  // subtotals are the same number and this is byte-for-byte the old behaviour.
   const bookingFeeAmount =
-    serverFeeAmount ?? computeBookingFeeAmount({ subtotal: totalAmount, fee: bookingFee });
+    serverFeeAmount ?? computeBookingFeeAmount({ subtotal: subtotals.floor, fee: bookingFee });
 
   // Keep only positive quantities in state — a ticket dropped to 0 is removed
   // entirely, so `items` never carries a 0-quantity entry (the orders endpoint
@@ -114,6 +155,26 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       return next;
     });
 
+  /**
+   * The buyer's chosen amount for one PWYW tier, PER UNIT.
+   *
+   * `null` forgets the choice and falls back to the tier's suggested amount —
+   * which is what an emptied input has to mean, since the alternative is
+   * treating a cleared box as a decision to pay zero.
+   *
+   * Deliberately NOT clamped as the buyer types: clamping on every keystroke
+   * makes "1" become the floor the moment it is typed and the buyer can never
+   * reach "15". The clamp is applied when the figure is read
+   * (`effectiveAmounts`), and again by the server, which is the one that counts.
+   */
+  const setTicketAmount = (ticketId: string, amount: number | null) =>
+    setPwywAmounts((prev) => {
+      const next = { ...prev };
+      if (amount != null && Number.isFinite(amount)) next[ticketId] = amount;
+      else delete next[ticketId];
+      return next;
+    });
+
   /**
    * Put this selection in the cart instead of paying for it now — the exit
    * that makes add-ons possible, because the buyer has to be able to leave for
@@ -139,7 +200,20 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       ticketMeta: Object.fromEntries(
         event.tickets
           .filter((t) => (selectedTickets[t.id] ?? 0) > 0)
-          .map((t) => [t.id, { title: t.title, price: t.price }]),
+          // `price` is the per-unit figure the cart displays and the checkout
+          // line carries — so on a PWYW tier it has to be the CHOSEN amount,
+          // not the floor, or the buyer's cart silently forgets what they
+          // picked on the way to an add-on and back. `pwywAmount` travels
+          // beside it because the bundle path sends the two separately: one is
+          // display, one is charged.
+          .map((t) => [
+            t.id,
+            {
+              title: t.title,
+              price: resolveUnitPrice(t, effectiveAmounts[t.id]),
+              ...(isPayWhatYouWant(t) ? { pwywAmount: effectiveAmounts[t.id] } : {}),
+            },
+          ]),
       ),
     });
     return true;
@@ -166,6 +240,9 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     try {
       const data = await createOrder.mutateAsync({
         items: selectedTickets,
+        // Omitted entirely when nothing in the cart is PWYW, so an ordinary
+        // purchase posts the same body it always did.
+        ...(Object.keys(effectiveAmounts).length > 0 ? { amounts: effectiveAmounts } : {}),
         email,
         firstName,
         lastName,
@@ -236,6 +313,14 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     setStep,
     selectedTickets,
     setTicketQty,
+    /**
+     * Raw buyer input per PWYW tier — only the tiers whose box has been touched.
+     * Bind an input to this; read `effectiveAmounts` to know what will be sent.
+     */
+    pwywAmounts,
+    setTicketAmount,
+    /** What each selected PWYW tier will actually be charged, per unit. */
+    effectiveAmounts,
     ticketCount,
     // The server's figure wins the moment there is one: start-payment first,
     // then the order response (which is already net of any discount), and only
@@ -249,6 +334,11 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       flow.result?.totalAmount ?? coupon.quote?.totalAmount ?? totalAmount + bookingFeeAmount,
     /** GROSS ticket total, before any discount OR booking fee. */
     subTotal: coupon.quote?.subTotal ?? totalAmount,
+    /**
+     * The same cart at every tier's MINIMUM. Equal to `subTotal` unless a PWYW
+     * tier is selected; the difference is what the buyer chose to add on top.
+     */
+    floorSubTotal: subtotals.floor,
     /**
      * The resolved fee RULE, for surfaces that quote a price with no cart behind
      * it (an event page's "From $25"). `null` when the artist charges none.

package/src/ui/index.ts

@@ -54,6 +54,10 @@ export {
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
 export { Cart, type CartProps } from "./styled/Cart";
+// The resolver is exported alongside the component because the Craft themes
+// are a separate rendering stack (Tailwind, not inline styles) and cannot use
+// the component — but the legacy `color`/`size` fallback must not diverge.
+export { CartLineOptions, resolveCartLineOptions } from "./styled/CartLineOptions";
 export { CurrencySwitcher, type CurrencySwitcherProps } from "./styled/CurrencySwitcher";
 export { UserMenu, type UserMenuProps } from "./styled/UserMenu";
 export { EmailListForm, type EmailListFormProps } from "./styled/EmailListForm";
@@ -153,6 +157,18 @@ export { PriceDisplay, priceTaxCaption, summarizeTaxQuote, type PriceDisplayProp
 // the styled blocks. Resolution stays on the server (`IEvent.bookingFee`); these
 // only do the arithmetic and the wording.
 export { computeBookingFeeAmount, hasBookingFee, describeBookingFee } from "./format/bookingFee";
+// Pay-what-you-want, for a site rendering its own ticket UI. `price` is the
+// FLOOR on a PWYW tier, so an existing "from $X" is already correct; these only
+// resolve what a buyer's chosen amount costs. The clamp here is UX — the server
+// clamps again and is the one that decides what is charged.
+export {
+  isPayWhatYouWant,
+  pwywMaximum,
+  pwywDefaultAmount,
+  clampChosenAmount,
+  resolveUnitPrice,
+  ticketSubtotals,
+} from "./format/pwyw";
 export { usePricesIncludeTax } from "../data/queries/useWebsite";
 
 // PWA (installable code sites) — SW registration + install/push UX (Tier 2).

package/src/ui/styled/AccountDashboard.tsx

@@ -36,6 +36,7 @@ import { Loading } from "./Loading";
 import { formatCountdown } from "./EventWaitlist";
 import { WalletPassButtons } from "./WalletPassButtons";
 import { TicketTransferPanel } from "./TicketTransfer";
+import { CartLineOptions } from "./CartLineOptions";
 
 export const ACCOUNT_TABS = [
   "membership",
@@ -924,6 +925,12 @@ function OrdersTab({ ctx }: { ctx: TabContext }) {
                     <div key={`${item.productVariantId}-${i}`} style={{ display: "flex", justifyContent: "space-between", fontSize: 14, padding: "4px 0" }}>
                       <span>
                         {item.title} × {item.quantity}
+                        {/* Which version. Two versions of one release carry the
+                            same title, so without this a buyer's own order
+                            history shows what looks like the same thing bought
+                            twice at two prices. Read from the snapshot taken at
+                            the sale, not re-resolved. */}
+                        <CartLineOptions item={item} accent={t.primary} size="small" style={{ marginTop: 2 }} />
                       </span>
                       <span>{formatAmount(item.price * item.quantity, order.currency || currency)}</span>
                     </div>

package/src/ui/styled/Cart.tsx

@@ -6,6 +6,7 @@ import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { readableTextOn } from "../theme/contrast";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { usePricesIncludeTax } from "../../data/queries/useWebsite";
+import { CartLineOptions } from "./CartLineOptions";
 
 export interface CartProps {
   /** Custom cart icon (defaults to a shopping bag). */
@@ -220,6 +221,11 @@ export function Cart({ icon, checkoutPath = "/i/checkout", productHref, formatAm
               {cartItems.map((item) => (
                   <div
                     key={item.productId + item.productVariantId + String(item.isGift) + (item.recipientEmail || "")}
+                    // Named so a test can assert on the LINE rather than the
+                    // page: the picker behind the drawer renders the same option
+                    // words, so an unscoped match passes whether or not the cart
+                    // shows anything.
+                    data-testid="cart-line"
                     style={{
                       display: "flex",
                       gap: 12,
@@ -257,14 +263,11 @@ export function Cart({ icon, checkoutPath = "/i/checkout", productHref, formatAm
                         {item.title}
                       </a>
                       <div style={{ fontSize: 14, opacity: 0.8 }}>{fmt(item.price)}</div>
-                      {item.color && item.size && (
-                        <div
-                          style={{ fontSize: 12, marginTop: 4, display: "flex", alignItems: "center", gap: 8, color: t.primary }}
-                        >
-                          <span style={{ width: 14, height: 14, borderRadius: "50%", background: item.color, display: "inline-block" }} />
-                          {item.size}
-                        </div>
-                      )}
+                      {/* Which version — "Format: FLAC". The old block required
+                          BOTH a colour and a size, so a line that was neither
+                          showed nothing at all and two versions of one release
+                          read as duplicates at two prices. */}
+                      <CartLineOptions item={item} accent={t.primary} />
                       {item.isGift && (
                         <div style={{ fontSize: 12, marginTop: 4, color: t.primary }}>
                           Gift for {item.recipientName} ({item.recipientEmail})

package/src/ui/styled/CartLineOptions.tsx

@@ -0,0 +1,107 @@
+import type { CSSProperties } from "react";
+
+import type { CartItem } from "../../contexts/CartContext";
+
+/**
+ * Which version a cart line is.
+ *
+ * Every surface that lists what someone is buying renders this, so the answer
+ * to "which one did I pick" is the same in the drawer, on the checkout page and
+ * on the receipt. They drifted before: the drawer and the confirmation each had
+ * their own copy of a colour-swatch-and-size block, and neither could name a
+ * "Format: FLAC" — so a buyer choosing between two versions of one release saw
+ * two identical lines at two prices.
+ *
+ * Renders nothing when there is nothing to say. A product sold one way has no
+ * versions to tell apart, and an empty row of chrome reads as a loading state.
+ */
+export function CartLineOptions({
+  item,
+  accent,
+  size = "normal",
+  style,
+}: {
+  item: Parameters<typeof resolveCartLineOptions>[0];
+  /** The theme's accent, so this sits with the surface rather than on it. */
+  accent: string;
+  size?: "normal" | "small";
+  style?: CSSProperties;
+}) {
+  const options = resolveCartLineOptions(item);
+  if (!options.length) return null;
+
+  const fontSize = size === "small" ? 11 : 12;
+  const dot = size === "small" ? 10 : 12;
+
+  return (
+    <div
+      style={{
+        fontSize,
+        marginTop: 4,
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        gap: 8,
+        color: accent,
+        ...style,
+      }}
+    >
+      {options.map((option) => (
+        <span key={`${option.axis}:${option.value}`} style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+          {option.swatchHex && (
+            <span
+              aria-hidden
+              style={{
+                width: dot,
+                height: dot,
+                borderRadius: "50%",
+                background: option.swatchHex,
+                display: "inline-block",
+              }}
+            />
+          )}
+          {/* The axis is named, not implied. "L" alone is ambiguous the moment a
+              product has more than one axis, and the creator chose the word. */}
+          <span style={{ opacity: 0.7 }}>{option.axis}{option.value ? ":" : ""}</span>
+          {/* A legacy colour is a bare hex with no name — the swatch says it
+              better than the string "#1a1a1a" does to someone about to pay. */}
+          {option.value && <span>{option.value}</span>}
+        </span>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * A line's options, whether it is a CART line or an ORDER line.
+ *
+ * Both answer the same question — which version is this — under two names. A
+ * cart line carries `options`, chosen a moment ago; an order line carries
+ * `variantOptions`, the snapshot taken when it was sold. Accepting both is what
+ * lets one component serve the drawer, the checkout, the receipt, the buyer's
+ * order history and the admin order page.
+ *
+ * ⚠️ Reading only `options` here TYPE-CHECKS against an order item, because
+ * both fields are optional — and silently renders the legacy fallback for every
+ * order ever placed.
+ *
+ * `color`/`size` last because carts persist in the browser and orders persist
+ * forever: a line saved before either field existed carries nothing else, and
+ * dropping it would blank the very detail this exists to show.
+ */
+export function resolveCartLineOptions(
+  item: Pick<CartItem, "options" | "color" | "size"> & {
+    variantOptions?: { axis: string; value: string; swatchHex?: string | null }[] | null;
+  },
+): { axis: string; value: string; swatchHex?: string | null }[] {
+  if (item.options?.length) return item.options;
+  if (item.variantOptions?.length) return item.variantOptions;
+
+  const legacy: { axis: string; value: string; swatchHex?: string | null }[] = [];
+  // A hex in `color` is a swatch with no name — which is exactly why the column
+  // was replaced. Shown as a swatch alone rather than printing "#1a1a1a" at
+  // someone about to pay.
+  if (item.color) legacy.push({ axis: "Colour", value: "", swatchHex: item.color });
+  if (item.size) legacy.push({ axis: "Size", value: item.size });
+  return legacy;
+}

package/src/ui/styled/Checkout.tsx

@@ -11,6 +11,7 @@ import { summarizeTaxQuote } from "../format/PriceDisplay";
 import { usePricesIncludeTax } from "../../data/queries/useWebsite";
 import { usePaymentRenderer } from "../payment/ForgePaymentProvider";
 import { Loading } from "./Loading";
+import { CartLineOptions } from "./CartLineOptions";
 
 export interface CheckoutProps {
   /** Path used to build the post-payment return URL. Defaults to `/checkout/finalise`. */
@@ -628,6 +629,10 @@ export function Checkout({
                       <p className="font-medium" style={{ color: theme.colors.text }}>
                         {item.title}
                       </p>
+                      {/* Which version. This page never showed it at all, so a
+                          cart holding the MP3 and the FLAC of one release
+                          reached payment as two identical rows. */}
+                      <CartLineOptions item={item} accent={theme.colors.primary} size="small" />
                       {item.isGift && (
                         <p className="text-xs" style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
                           Gift for {item.recipientName}

package/src/ui/styled/CheckoutConfirmation.tsx

@@ -20,6 +20,7 @@ import { BundleConfirmation } from "./BundleConfirmation";
 import { useCart } from "../../contexts/CartContext";
 import { usePublicAuth } from "../../contexts/PublicAuthContext";
 import { OrderStatus, ProductDeliveryType, type IPublicOrder } from "../../types/models";
+import { CartLineOptions } from "./CartLineOptions";
 
 export interface CheckoutConfirmationProps {
   orderId?: string;
@@ -419,12 +420,9 @@ function GroupBlock({
               <div style={{ fontSize: 12, color: alpha(text, 0.6), marginTop: 2 }}>
                 {fmt(item.price)} · Qty {item.quantity}
               </div>
-              {item.color && item.size && (
-                <div style={{ fontSize: 12, marginTop: 4, display: "flex", alignItems: "center", gap: 6, color: alpha(text, 0.7) }}>
-                  <span style={{ width: 12, height: 12, borderRadius: "50%", background: item.color, display: "inline-block", border: `1px solid ${alpha(text, 0.2)}` }} />
-                  {item.size}
-                </div>
-              )}
+              {/* Which version — the receipt has to say, or a buyer cannot check
+                  they were charged for the one they picked. */}
+              <CartLineOptions item={item} accent={primary} size="small" />
               {item.isGift && (
                 <div style={{ fontSize: 12, marginTop: 4, color: primary }}>
                   🎁 Gift for {item.recipientName} ({item.recipientEmail})

package/src/ui/styled/EventTickets.tsx

@@ -5,6 +5,7 @@ import { useEventCheckout } from "../headless/event/useEventCheckout";
 import { useForgeTheme, type ForgeTheme } from "../theme/ForgeThemeProvider";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { PriceDisplay, summarizeTaxQuote } from "../format/PriceDisplay";
+import { clampChosenAmount, isPayWhatYouWant, pwywDefaultAmount, pwywMaximum } from "../format/pwyw";
 import { usePricesIncludeTax } from "../../data/queries/useWebsite";
 import { Loading } from "./Loading";
 import { usePaymentRenderer, type PaymentRenderProps } from "../payment/ForgePaymentProvider";
@@ -282,6 +283,12 @@ function TicketStep({
                         {fmt(Number(ticket.compareAtPrice))}
                       </span>
                     )}
+                    {/* On a PWYW tier `price` is the FLOOR, so it is labelled as
+                        one — showing it bare would read as a fixed price the
+                        buyer is about to be charged. */}
+                    {isPayWhatYouWant(ticket) && (
+                      <span style={{ fontSize: 14, fontWeight: 500, opacity: 0.7, marginRight: 6 }}>from</span>
+                    )}
                     <PriceDisplay amount={Number(ticket.price)} pricesIncludeTax={pricesIncludeTax} formatAmount={fmt} mutedColor={theme.colors.text} captionStyle={{ opacity: 0.65 }} />
                   </div>
                 </div>
@@ -305,6 +312,20 @@ function TicketStep({
                   </button>
                 </div>
               </div>
+              {/* The amount box appears only once a seat is actually selected —
+                  before that there is nothing to price, and a row of empty
+                  inputs down the tier list reads as a form to fill in rather
+                  than a choice to make. */}
+              {isPayWhatYouWant(ticket) && selectedQty > 0 && !isSoldOut && !isExpired && (
+                <PwywAmountField
+                  ticket={ticket}
+                  quantity={selectedQty}
+                  value={c.pwywAmounts[ticket.id]}
+                  onChange={(amount) => c.setTicketAmount(ticket.id, amount)}
+                  fmt={fmt}
+                  theme={theme}
+                />
+              )}
               {ticket.description && (
                 <p dangerouslySetInnerHTML={{ __html: ticket.description }} style={{ marginTop: 12, fontSize: 14 }} />
               )}
@@ -669,6 +690,99 @@ const closeButtonStyle = (t: ForgeTheme): CSSProperties => ({
   opacity: 0.7,
 });
 
+/**
+ * The buyer's "what will you pay?" box for one pay-what-you-want tier.
+ *
+ * Holds its own STRING state rather than binding the number straight through.
+ * Two reasons, both of which are broken inputs if you skip them: an empty box
+ * has to stay empty while the buyer retypes (a number-bound input snaps it back
+ * to the floor on every keystroke), and "1" on the way to "15" must not be
+ * clamped up to the minimum the instant it is typed.
+ *
+ * Correction happens on BLUR, when the buyer has finished — and the server
+ * clamps again regardless, so nothing here is load-bearing for money.
+ */
+function PwywAmountField({
+  ticket,
+  quantity,
+  value,
+  onChange,
+  fmt,
+  theme,
+}: {
+  ticket: ITicket;
+  quantity: number;
+  value: number | undefined;
+  onChange: (amount: number | null) => void;
+  fmt: (amount: number) => string;
+  theme: ForgeTheme;
+}) {
+  const floor = Number(ticket.price);
+  const maximum = pwywMaximum(ticket);
+  const suggested = pwywDefaultAmount(ticket);
+  const [draft, setDraft] = useState<string>(String(value ?? suggested));
+
+  // Follow the tier's own default when the buyer hasn't typed anything — an
+  // operator's suggested amount arriving late (or the selection being cleared
+  // and remade) should re-seed the box rather than leave a stale figure.
+  useEffect(() => {
+    if (value == null) setDraft(String(suggested));
+  }, [value, suggested]);
+
+  const parsed = Number(draft);
+  const effective = Number.isFinite(parsed) ? clampChosenAmount(ticket, parsed) : floor;
+  const belowFloor = draft.trim() !== "" && Number.isFinite(parsed) && parsed < floor;
+  const aboveMax = maximum != null && Number.isFinite(parsed) && parsed > maximum;
+
+  const commit = () => {
+    if (draft.trim() === "" || !Number.isFinite(parsed)) {
+      onChange(null);
+      setDraft(String(suggested));
+      return;
+    }
+    const clamped = clampChosenAmount(ticket, parsed);
+    onChange(clamped);
+    setDraft(String(clamped));
+  };
+
+  return (
+    <div style={{ marginTop: 12 }}>
+      <label
+        htmlFor={`pwyw-${ticket.id}`}
+        style={{ display: "block", fontSize: 13, fontWeight: 600, marginBottom: 6 }}
+      >
+        Name your price
+        <span style={{ fontWeight: 400, opacity: 0.7 }}>
+          {" "}
+          — minimum {fmt(floor)}
+          {maximum != null ? `, up to ${fmt(maximum)}` : ""}
+        </span>
+      </label>
+      <input
+        id={`pwyw-${ticket.id}`}
+        type="number"
+        inputMode="decimal"
+        min={floor}
+        {...(maximum != null ? { max: maximum } : {})}
+        step="0.01"
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        onBlur={commit}
+        style={{ ...inputStyle(theme), maxWidth: 200 }}
+      />
+      <p style={{ fontSize: 12, opacity: 0.7, marginTop: 6 }}>
+        {belowFloor
+          ? `The minimum is ${fmt(floor)} — we'll use that.`
+          : aboveMax
+            ? `The most you can pay is ${fmt(maximum!)} — we'll use that.`
+            : quantity > 1
+              ? `${fmt(effective)} each · ${fmt(effective * quantity)} for ${quantity}`
+              : "Per ticket."}
+      </p>
+    </div>
+  );
+}
+
 const stepperStyle = (t: ForgeTheme, filled: boolean): CSSProperties => ({
   width: 40,
   height: 40,

package/src/ui/styled/ProductDetail.tsx

@@ -112,6 +112,14 @@ function useBuy(product: IPublicProduct, cover: string | undefined, checkoutPath
       quantity: opts?.quantity ?? 1,
       canIncreaseQuantity: opts?.canIncreaseQuantity ?? true,
       payWhatYouWant: !!variant.payWhatYouWant,
+      // Which version was chosen, carried onto the line so the cart, the
+      // checkout and the receipt can all say so. `color`/`size` stay for a
+      // moment longer: they are what a cart saved before this holds.
+      options: (variant.options ?? []).map((option) => ({
+        axis: option.axis,
+        value: option.value,
+        swatchHex: option.swatchHex,
+      })),
       color: variant.color,
       size: variant.size,
       deliveryType: variant.deliveryType,