@tribe-nest/forge 3.20.0 → 3.22.0

package/src/ui/styled/_tests/PresaleCode.spec.tsx

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import { PresaleCodeField } from "../PresaleCode";
+import type { PresaleCodeField as PresaleCodeState } from "../../headless/event/usePresaleCode";
+
+/**
+ * Events 1.2 — the box a buyer types a presale code into.
+ *
+ * Rendered through `react-dom/server`, which needs no DOM, so these run in the
+ * package's existing node vitest environment. Effects never fire under
+ * `renderToStaticMarkup`, so the state fixture is the only data source and
+ * nothing reaches the network.
+ *
+ * This is the REAL component the Forge storefront renders, and the client app's
+ * own copy is a presentational twin driven by the same `usePresaleCode` state —
+ * so what is asserted here about WHAT IS SAID holds on both rendering stacks.
+ */
+
+function state(overrides: Partial<PresaleCodeState> = {}): PresaleCodeState {
+  return {
+    event: undefined,
+    isLoading: false,
+    visible: true,
+    input: "",
+    setInput: () => {},
+    code: null,
+    status: "idle",
+    message: null,
+    submit: () => {},
+    clear: () => {},
+    isUnlocked: false,
+    ...overrides,
+  };
+}
+
+const theme = { colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 };
+
+const render = (presale: PresaleCodeState) =>
+  renderToStaticMarkup(
+    <ForgeThemeProvider theme={theme}>
+      <PresaleCodeField presale={presale} />
+    </ForgeThemeProvider>,
+  );
+
+describe("PresaleCodeField", () => {
+  it("REGRESSION: renders NOTHING on an event with no coded tier", () => {
+    // The whole reason `hasCodedTiers` is a server fact. A code box on an
+    // ordinary event tells a buyer there is a secret they are missing and gives
+    // them no way to discover there isn't one.
+    const html = render(state({ visible: false }));
+    // The provider still emits its :root variables; nothing of the FIELD is there.
+    expect(html).not.toContain("presale-code");
+    expect(html).not.toContain("presale code");
+  });
+
+  it("offers the prompt and an input when a presale exists", () => {
+    const html = render(state());
+    expect(html).toContain("Have a presale code?");
+    expect(html).toContain('data-testid="presale-code-input"');
+    expect(html).toContain("Unlock");
+  });
+
+  it("disables Unlock until something is typed", () => {
+    expect(render(state())).toContain("disabled");
+    expect(render(state({ input: "PRESALE24" }))).not.toContain("disabled");
+  });
+
+  it("says the code is not valid for the EVENT, naming no tier", () => {
+    const html = render(
+      state({ code: "GUESS", status: "rejected", message: "That code isn't valid for this event." }),
+    );
+    expect(html).toContain("That code isn&#x27;t valid for this event.");
+    // A refusal that named a tier — "that isn't the VIP code" — would turn the
+    // box into a way to enumerate them.
+    expect(html.toLowerCase()).not.toContain("tier");
+    expect(html).toContain('role="alert"');
+    expect(html).toContain('aria-invalid="true"');
+  });
+
+  it("confirms an accepted code, with a way to remove it", () => {
+    // Without this, a code for a tier that was already VISIBLE (code-gated but
+    // listed) appears to do nothing at all: the tier list is unchanged.
+    const html = render(state({ code: "PRESALE24", status: "accepted", isUnlocked: true, message: "Code applied." }));
+    expect(html).toContain("Presale unlocked — PRESALE24");
+    expect(html).toContain('data-testid="presale-code-remove"');
+    // The input is gone — there is nothing left to type.
+    expect(html).not.toContain('data-testid="presale-code-input"');
+  });
+
+  it("shows a pending state while the server decides", () => {
+    const html = render(state({ code: "PRESALE24", input: "PRESALE24", status: "checking" }));
+    expect(html).toContain("Checking…");
+    // No verdict yet, so no message either way.
+    expect(html).not.toContain('data-testid="presale-code-message"');
+  });
+
+  it("takes its colours from the theme, not a hardcoded palette", () => {
+    const html = renderToStaticMarkup(
+      <ForgeThemeProvider theme={{ ...theme, colors: { ...theme.colors, primary: "#0f766e" } }}>
+        <PresaleCodeField presale={state({ code: "X", status: "accepted", isUnlocked: true })} />
+      </ForgeThemeProvider>,
+    );
+    expect(html).toContain("#0f766e");
+  });
+});

package/src/utils/_tests/presaleCode.spec.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  readPresaleCode,
+  readPresaleCodeFromUrl,
+  subscribePresaleCode,
+  writePresaleCode,
+} from "../presaleCode";
+
+/**
+ * Events 1.2 — where a buyer's presale code lives between typing it and paying
+ * with it.
+ *
+ * This is the part that stops the feature being a toy. The sell guard
+ * re-evaluates the code on the ORDER, not just on the read that revealed the
+ * tier, so a code that does not survive from the event page to the payment step
+ * produces the worst possible outcome: the buyer unlocks a presale, fills in
+ * their details, and is refused at the card.
+ *
+ * The package's vitest environment is `node`, so `window` is stubbed here
+ * rather than assumed. That is also the point of the SSR case below — every
+ * function has to be callable with no `window` at all, because Forge renders on
+ * a Cloudflare Worker first.
+ */
+
+type Store = Record<string, string>;
+
+function stubWindow(initial: Store = {}) {
+  const store: Store = { ...initial };
+  vi.stubGlobal("window", {
+    sessionStorage: {
+      getItem: (k: string) => store[k] ?? null,
+      setItem: (k: string, v: string) => {
+        store[k] = v;
+      },
+      removeItem: (k: string) => {
+        delete store[k];
+      },
+    },
+    location: { href: "https://artist.test/events/the-show" },
+  });
+  return store;
+}
+
+// The module memoises per key, so every test uses a fresh event id.
+let n = 0;
+const key = () => `event-${++n}`;
+
+beforeEach(() => stubWindow());
+afterEach(() => vi.unstubAllGlobals());
+
+describe("presale code storage", () => {
+  it("round-trips a code for one event", () => {
+    const k = key();
+    writePresaleCode(k, "PRESALE24");
+    expect(readPresaleCode(k)).toBe("PRESALE24");
+  });
+
+  it("keeps two events' codes apart", () => {
+    // Two presales are two different codes; a shared slot would silently apply
+    // one show's code to another.
+    const a = key();
+    const b = key();
+    writePresaleCode(a, "AAA");
+    writePresaleCode(b, "BBB");
+    expect(readPresaleCode(a)).toBe("AAA");
+    expect(readPresaleCode(b)).toBe("BBB");
+  });
+
+  it("survives a reload — the whole reason it is not component state", () => {
+    const k = key();
+    const store = stubWindow();
+    writePresaleCode(k, "PRESALE24");
+    expect(store[`tn:presale:${k}`]).toBe("PRESALE24");
+
+    // A fresh page: same sessionStorage, module memory not yet primed for a key
+    // it has never seen.
+    const fresh = key();
+    stubWindow({ [`tn:presale:${fresh}`]: "FROMSTORAGE" });
+    expect(readPresaleCode(fresh)).toBe("FROMSTORAGE");
+  });
+
+  it("trims what the buyer typed", () => {
+    const k = key();
+    writePresaleCode(k, "  presale24 ");
+    expect(readPresaleCode(k)).toBe("presale24");
+  });
+
+  it("clearing removes it from storage too, not just from memory", () => {
+    const k = key();
+    const store = stubWindow();
+    writePresaleCode(k, "PRESALE24");
+    writePresaleCode(k, null);
+    expect(readPresaleCode(k)).toBeNull();
+    expect(store[`tn:presale:${k}`]).toBeUndefined();
+  });
+
+  it("an empty or whitespace code clears rather than storing blank", () => {
+    const k = key();
+    writePresaleCode(k, "PRESALE24");
+    writePresaleCode(k, "   ");
+    expect(readPresaleCode(k)).toBeNull();
+  });
+
+  it("notifies every subscriber — the page and the ticket modal are separate components", () => {
+    const k = key();
+    const seen: (string | null)[] = [];
+    const unsubscribe = subscribePresaleCode(() => seen.push(readPresaleCode(k)));
+
+    writePresaleCode(k, "PRESALE24");
+    writePresaleCode(k, null);
+    unsubscribe();
+    writePresaleCode(k, "IGNORED");
+
+    expect(seen).toEqual(["PRESALE24", null]);
+  });
+
+  it("survives storage being unavailable (private mode) without throwing", () => {
+    const k = key();
+    vi.stubGlobal("window", {
+      sessionStorage: {
+        getItem: () => {
+          throw new Error("denied");
+        },
+        setItem: () => {
+          throw new Error("denied");
+        },
+        removeItem: () => {
+          throw new Error("denied");
+        },
+      },
+      location: { href: "https://artist.test/" },
+    });
+
+    expect(() => writePresaleCode(k, "PRESALE24")).not.toThrow();
+    // Still applied for this page view — it just will not survive a reload.
+    expect(readPresaleCode(k)).toBe("PRESALE24");
+  });
+
+  it("is inert on the server, where Forge renders first", () => {
+    vi.stubGlobal("window", undefined);
+    const k = key();
+    expect(readPresaleCode(k)).toBeNull();
+    expect(readPresaleCodeFromUrl()).toBeNull();
+    expect(() => writePresaleCode(k, "PRESALE24")).not.toThrow();
+  });
+});
+
+describe("presale code on the URL", () => {
+  it("reads ?accessCode — what makes a mailed presale link work on arrival", () => {
+    vi.stubGlobal("window", {
+      sessionStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
+      location: { href: "https://artist.test/events/the-show?accessCode=PRESALE24" },
+    });
+    expect(readPresaleCodeFromUrl()).toBe("PRESALE24");
+  });
+
+  it("is null when the link carries no code", () => {
+    expect(readPresaleCodeFromUrl()).toBeNull();
+  });
+
+  it("ignores a blank parameter rather than applying an empty code", () => {
+    vi.stubGlobal("window", {
+      sessionStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
+      location: { href: "https://artist.test/events/the-show?accessCode=%20%20" },
+    });
+    expect(readPresaleCodeFromUrl()).toBeNull();
+  });
+});

package/src/utils/_tests/structuredData.spec.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildCourseSchema,
+  buildEntitySchema,
+  buildEntityReviewSchema,
+  buildProductSchema,
+  buildServiceSchema,
+  jsonLdScripts,
+  type ProductSchemaSource,
+} from "../structuredData";
+
+/**
+ * The regression this file exists for: `buildEntityReviewSchema` used to return
+ * `null` whenever an entity had no review aggregate, so a brand-new product —
+ * the one that most needs a rich result and a free Shopping listing — emitted
+ * no schema.org/Product at all.
+ *
+ * Reviews must ENRICH the node, never gate it. The mirror-image rule is that an
+ * empty or zero `aggregateRating` is a schema violation Google penalises, so
+ * "no reviews yet" must be an ABSENT key, not a zero.
+ */
+
+const PRODUCT: ProductSchemaSource = {
+  title: "Midnight Pressing (Vinyl)",
+  description: "<p>Limited <strong>180g</strong> pressing.</p>",
+  artist: "Nova Wren",
+  media: [
+    { url: "https://cdn.example/front.jpg", type: "image/jpeg" },
+    { url: "https://cdn.example/back.jpg", type: "image/jpeg" },
+  ],
+  variants: [{ price: 32, availabilityStatus: "active" }],
+};
+
+describe("buildProductSchema — reviews enrich, they do not gate", () => {
+  it("emits a Product for a product with NO reviews at all", () => {
+    const schema = buildProductSchema(PRODUCT, { currency: "USD" });
+    expect(schema).not.toBeNull();
+    expect(schema).toMatchObject({ "@context": "https://schema.org", "@type": "Product", name: PRODUCT.title });
+  });
+
+  it("omits aggregateRating entirely rather than emitting a zero", () => {
+    for (const aggregate of [null, undefined, { avgRating: 0, reviewCount: 0 }]) {
+      const schema = buildProductSchema({ ...PRODUCT, reviewAggregate: aggregate }, { currency: "USD" })!;
+      expect(schema).not.toHaveProperty("aggregateRating");
+      expect(schema).not.toHaveProperty("review");
+    }
+  });
+
+  it("adds aggregateRating once there genuinely are reviews", () => {
+    const schema = buildProductSchema(
+      { ...PRODUCT, reviewAggregate: { avgRating: 4.6666, reviewCount: 3 } },
+      {
+        currency: "USD",
+        reviews: [{ rating: 5, title: "Superb", body: "Sounds huge.", reviewerName: "Ada", publishedAt: "2026-01-02" }],
+      },
+    )!;
+    expect(schema.aggregateRating).toEqual({
+      "@type": "AggregateRating",
+      ratingValue: 4.67,
+      reviewCount: 3,
+      bestRating: 5,
+      worstRating: 1,
+    });
+    expect(schema.review).toHaveLength(1);
+  });
+
+  it("drops out-of-range review ratings from the sample", () => {
+    const schema = buildProductSchema(
+      { ...PRODUCT, reviewAggregate: { avgRating: 5, reviewCount: 2 } },
+      { currency: "USD", reviews: [{ rating: 5 }, { rating: 0 }, { rating: 9 }] },
+    )!;
+    expect(schema.review).toHaveLength(1);
+  });
+
+  it("returns null only when there is no name — nothing truthful to say", () => {
+    expect(buildProductSchema(null, { currency: "USD" })).toBeNull();
+    expect(buildProductSchema({ title: "   " }, { currency: "USD" })).toBeNull();
+  });
+});
+
+describe("buildProductSchema — offers stay honest", () => {
+  it("emits a single Offer for one fixed price", () => {
+    const schema = buildProductSchema(PRODUCT, { currency: "GBP" })!;
+    expect(schema.offers).toEqual({
+      "@type": "Offer",
+      priceCurrency: "GBP",
+      price: 32,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("emits NO offers without a settlement currency — an Offer with no currency is invalid", () => {
+    expect(buildProductSchema(PRODUCT, {})!).not.toHaveProperty("offers");
+    expect(buildProductSchema(PRODUCT, { currency: null })!).not.toHaveProperty("offers");
+  });
+
+  it("emits NO offers for a product the caller may not buy (membership gate)", () => {
+    const gated = buildProductSchema({ ...PRODUCT, membershipGate: { allowed: false } }, { currency: "USD" })!;
+    expect(gated).not.toHaveProperty("offers");
+    // …but the Product node itself still exists, so the page is still indexable.
+    expect(gated["@type"]).toBe("Product");
+
+    const allowed = buildProductSchema({ ...PRODUCT, membershipGate: { allowed: true } }, { currency: "USD" })!;
+    expect(allowed).toHaveProperty("offers");
+  });
+
+  it("mirrors availabilityStatus — the same field the Add-to-cart button reads", () => {
+    const soldOut = buildProductSchema(
+      { ...PRODUCT, variants: [{ price: 32, availabilityStatus: "temporarily_out_of_stock" }] },
+      { currency: "USD" },
+    )!;
+    expect(soldOut.offers).toMatchObject({ availability: "https://schema.org/OutOfStock" });
+
+    const partial = buildProductSchema(
+      {
+        ...PRODUCT,
+        variants: [
+          { price: 32, availabilityStatus: "temporarily_out_of_stock" },
+          { price: 45, availabilityStatus: "active" },
+        ],
+      },
+      { currency: "USD" },
+    )!;
+    expect(partial.offers).toMatchObject({ availability: "https://schema.org/InStock" });
+  });
+
+  it("emits an AggregateOffer across several variant prices", () => {
+    const schema = buildProductSchema(
+      {
+        ...PRODUCT,
+        variants: [
+          { price: 32, availabilityStatus: "active" },
+          { price: "45.5", availabilityStatus: "active" },
+          { price: 40, availabilityStatus: "active" },
+        ],
+      },
+      { currency: "EUR" },
+    )!;
+    expect(schema.offers).toEqual({
+      "@type": "AggregateOffer",
+      priceCurrency: "EUR",
+      lowPrice: 32,
+      highPrice: 45.5,
+      offerCount: 3,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("leaves highPrice OFF for an open-ended pay-what-you-want floor", () => {
+    // `price` IS the floor for a PWYW variant; with no maximum there is no
+    // ceiling, and inventing one would be a claim the storefront cannot back.
+    const schema = buildProductSchema(
+      { ...PRODUCT, variants: [{ price: 5, availabilityStatus: "active", payWhatYouWant: true }] },
+      { currency: "USD" },
+    )!;
+    expect(schema.offers).toEqual({
+      "@type": "AggregateOffer",
+      priceCurrency: "USD",
+      lowPrice: 5,
+      offerCount: 1,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("uses the pay-what-you-want maximum as highPrice when one is set", () => {
+    const schema = buildProductSchema(
+      {
+        ...PRODUCT,
+        variants: [{ price: 5, availabilityStatus: "active", payWhatYouWant: true, payWhatYouWantMaximum: 50 }],
+      },
+      { currency: "USD" },
+    )!;
+    expect(schema.offers).toMatchObject({ "@type": "AggregateOffer", lowPrice: 5, highPrice: 50 });
+  });
+
+  it("emits no offers for a product with no variants", () => {
+    expect(buildProductSchema({ ...PRODUCT, variants: [] }, { currency: "USD" })!).not.toHaveProperty("offers");
+  });
+});
+
+describe("buildProductSchema — the rest of the node", () => {
+  it("strips HTML out of the description", () => {
+    expect(buildProductSchema(PRODUCT, {})!.description).toBe("Limited 180g pressing.");
+  });
+
+  it("emits every image, and a bare string when there is only one", () => {
+    expect(buildProductSchema(PRODUCT, {})!.image).toEqual([
+      "https://cdn.example/front.jpg",
+      "https://cdn.example/back.jpg",
+    ]);
+    const single = buildProductSchema({ ...PRODUCT, media: [PRODUCT.media![0]] }, {})!;
+    expect(single.image).toBe("https://cdn.example/front.jpg");
+  });
+
+  it("prefers the release artist as brand, falling back to the creator", () => {
+    expect(buildProductSchema(PRODUCT, { brand: "Wren Records" })!.brand).toEqual({
+      "@type": "Organization",
+      name: "Nova Wren",
+    });
+    expect(buildProductSchema({ ...PRODUCT, artist: "" }, { brand: "Wren Records" })!.brand).toEqual({
+      "@type": "Organization",
+      name: "Wren Records",
+    });
+    expect(buildProductSchema({ ...PRODUCT, artist: "" }, {})!).not.toHaveProperty("brand");
+  });
+
+  it("omits url when the caller has no canonical URL to give", () => {
+    expect(buildProductSchema(PRODUCT, {})!).not.toHaveProperty("url");
+    expect(buildProductSchema(PRODUCT, { url: "https://nova.example/i/store/vinyl" })!.url).toBe(
+      "https://nova.example/i/store/vinyl",
+    );
+  });
+});
+
+describe("buildCourseSchema / buildServiceSchema", () => {
+  const COURSE = { title: "Mixing in a Bedroom", description: "<p>8 modules.</p>", price: "99", media: [] };
+
+  it("emits a Course with no reviews, and uses `provider` not `brand`", () => {
+    const schema = buildCourseSchema(COURSE, { currency: "USD", brand: "Nova Wren" })!;
+    expect(schema["@type"]).toBe("Course");
+    expect(schema.provider).toEqual({ "@type": "Organization", name: "Nova Wren" });
+    expect(schema).not.toHaveProperty("brand");
+    expect(schema).not.toHaveProperty("aggregateRating");
+    expect(schema.offers).toEqual({
+      "@type": "Offer",
+      priceCurrency: "USD",
+      price: 99,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("never claims hasCourseInstance — the platform has no scheduled instance to point at", () => {
+    expect(buildCourseSchema(COURSE, { currency: "USD" })!).not.toHaveProperty("hasCourseInstance");
+  });
+
+  it("drops the Course offer for a members-only course", () => {
+    const schema = buildCourseSchema({ ...COURSE, membershipGate: { allowed: false } }, { currency: "USD" })!;
+    expect(schema["@type"]).toBe("Course");
+    expect(schema).not.toHaveProperty("offers");
+  });
+
+  it("emits a Service for a coaching product with no reviews", () => {
+    const schema = buildServiceSchema({ title: "1:1 Mix Review", price: "150" }, { currency: "USD" })!;
+    expect(schema["@type"]).toBe("Service");
+    expect(schema.offers).toMatchObject({ "@type": "Offer", price: 150 });
+    expect(schema).not.toHaveProperty("aggregateRating");
+  });
+
+  it("emits no offer for a free/unpriced entity's missing price", () => {
+    expect(buildServiceSchema({ title: "1:1 Mix Review", price: null }, { currency: "USD" })!).not.toHaveProperty(
+      "offers",
+    );
+    // Zero is a real price (a free course), not a missing one.
+    expect(buildCourseSchema({ ...COURSE, price: 0 }, { currency: "USD" })!.offers).toMatchObject({ price: 0 });
+  });
+});
+
+describe("buildEntitySchema + jsonLdScripts", () => {
+  it("keeps buildEntityReviewSchema as an alias so a deployed site's import survives", () => {
+    expect(buildEntityReviewSchema).toBe(buildEntitySchema);
+    // …and the alias no longer returns null for an unreviewed entity.
+    expect(buildEntityReviewSchema({ type: "Product", name: "Tote" })).not.toBeNull();
+  });
+
+  it("produces one ld+json script per non-null schema, and drops nulls", () => {
+    const scripts = jsonLdScripts(buildProductSchema(PRODUCT, { currency: "USD" }), null, undefined);
+    expect(scripts).toHaveLength(1);
+    expect(scripts[0].type).toBe("application/ld+json");
+    expect(JSON.parse(scripts[0].children)["@type"]).toBe("Product");
+  });
+
+  it("returns an empty array so a head() can spread it unconditionally", () => {
+    expect(jsonLdScripts(buildProductSchema(null))).toEqual([]);
+  });
+});

package/src/utils/presaleCode.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a buyer's presale code lives between typing it and paying with it.
+ *
+ * ## Why this is a module-level store and not component state
+ *
+ * The code has to be in three places at once, in components that do not share a
+ * parent: the event page's own `useEvent` (to reveal the hidden tiers), the
+ * ticket modal's `useEventCheckout` (its own separate `useEvent`), and the
+ * order body (the sell guard re-checks the code on every purchase, so a buyer
+ * who unlocks a tier and then checks out without the code is refused AFTER
+ * entering their card). Threading it through props would work for one host app
+ * and break for every code-site that composes the Forge pieces differently.
+ *
+ * ## Why sessionStorage and not localStorage
+ *
+ * A presale code is a right to buy now, not a saved preference. Session scope
+ * survives the reload, the Stripe redirect and the back button — everything
+ * inside one purchase — and does not silently re-apply a spent code to a
+ * different show weeks later.
+ *
+ * Keyed per event, because two presales are two different codes.
+ */
+
+const KEY_PREFIX = "tn:presale:";
+
+/** eventKey → code, mirroring sessionStorage so reads are synchronous. */
+const memory = new Map<string, string>();
+const listeners = new Set<() => void>();
+
+/** Loaded lazily so a server render never touches storage. */
+const hydrated = new Set<string>();
+
+const storageKey = (eventKey: string) => `${KEY_PREFIX}${eventKey}`;
+
+function hydrate(eventKey: string): void {
+  if (hydrated.has(eventKey) || typeof window === "undefined") return;
+  hydrated.add(eventKey);
+  try {
+    const stored = window.sessionStorage.getItem(storageKey(eventKey));
+    if (stored) memory.set(eventKey, stored);
+  } catch {
+    // Private mode / disabled storage. The code still works for this render;
+    // it just will not survive a reload.
+  }
+}
+
+export function readPresaleCode(eventKey: string): string | null {
+  if (!eventKey) return null;
+  hydrate(eventKey);
+  return memory.get(eventKey) ?? null;
+}
+
+export function writePresaleCode(eventKey: string, code: string | null): void {
+  if (!eventKey) return;
+  hydrated.add(eventKey);
+  const trimmed = code?.trim();
+  if (trimmed) memory.set(eventKey, trimmed);
+  else memory.delete(eventKey);
+
+  if (typeof window !== "undefined") {
+    try {
+      if (trimmed) window.sessionStorage.setItem(storageKey(eventKey), trimmed);
+      else window.sessionStorage.removeItem(storageKey(eventKey));
+    } catch {
+      // As above — in-memory only.
+    }
+  }
+
+  for (const listener of listeners) listener();
+}
+
+export function subscribePresaleCode(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * `?accessCode=PRESALE24` on the URL, so the link an artist mails to their list
+ * unlocks the page on arrival instead of asking the recipient to retype what
+ * they just clicked.
+ *
+ * The parameter is left ON the URL deliberately, unlike the attribution ref: a
+ * presale link is meant to be forwardable, and stripping it would break the
+ * one thing the recipient is most likely to do with it.
+ */
+export function readPresaleCodeFromUrl(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const value = new URL(window.location.href).searchParams.get("accessCode");
+    return value?.trim() || null;
+  } catch {
+    return null;
+  }
+}