@tribe-nest/forge 3.26.0 → 3.31.0

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.26.0",
+  "version": "3.31.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Forge \u2014 the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
+  "description": "Forge: the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
   "exports": {
     ".": "./src/index.ts",
     "./ui": "./src/ui/index.ts",
     "./ui/headless": "./src/ui/headless/index.ts",
-    "./server": "./src/server/index.ts"
+    "./server": "./src/server/index.ts",
+    "./media": "./src/ui/media/index.ts"
   },
   "files": [
     "src"
@@ -26,6 +27,8 @@
     "@stripe/react-stripe-js": "^3.8.0",
     "@stripe/stripe-js": "^7.6.1",
     "@tanstack/react-query": "^5.62.7",
+    "@tribe-nest/media-client": "^0.1.0",
+    "@tribe-nest/media-protocol": "^1.0.0",
     "axios": "^1.7.9",
     "lucide-react": "^0.510.0",
     "react-hook-form": "^7.60.0",

package/src/_tests/publishedResolvability.spec.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+/**
+ * Can a creator site actually INSTALL what this package imports?
+ *
+ * Forge is unusual twice over. It publishes RAW SOURCE (`"files": ["src"]`, an
+ * exports map pointing at `./src/...`, no build step), so every import in this
+ * tree is resolved by the CONSUMER'S bundler against the CONSUMER'S
+ * `node_modules` - not by anything in this repo. And a creator site is a
+ * site-starter fork whose `package.json` lists `@tribe-nest/forge` and nothing
+ * else, so the only packages present are Forge's own declared dependencies.
+ *
+ * Inside the monorepo none of that is visible: npm workspaces symlink every
+ * package in `packages/` into `node_modules`, so an import resolves whether or
+ * not it was ever declared, and whether or not the package it names is
+ * publishable at all. Every spec in this package, and every `check-types` run,
+ * passes under those symlinks.
+ *
+ * The failure this exists for actually shipped. `./media` - the entry point that
+ * holds `BookingCallProvider`, the ONLY surface that can enter a coaching video
+ * room - imports the two media packages, both of which were `"private": true`
+ * (so npm would never publish them) and declared only as OPTIONAL peer
+ * dependencies (so npm would never install them). `./media` is registered in
+ * `ENTRY_SUBPATHS` in
+ * `apps/backend/src/utils/forgeManifest.ts` precisely so the code agent learns
+ * it exists and writes `import { BookingCallProvider } from
+ * "@tribe-nest/forge/media"` - an import that failed at install on every real
+ * creator site, while the whole suite stayed green and the starter's release
+ * notes announced the feature.
+ *
+ * So there are two properties here and they are separate:
+ *
+ *  1. every bare import in the published tree names a package the consumer's
+ *     install will actually produce (a dependency, or a peer that npm installs
+ *     because it is NOT marked optional), and
+ *  2. every workspace package Forge depends on is one npm will publish.
+ *
+ * Specs are excluded: they never ship (`files` is `["src"]`, but a consumer
+ * never imports a `.spec` file), and they legitimately reach for vitest, jsdom
+ * and node builtins.
+ */
+
+const FORGE_ROOT = join(__dirname, "..", "..");
+const PACKAGES_ROOT = join(FORGE_ROOT, "..");
+
+type PackageJson = {
+  name: string;
+  private?: boolean;
+  files?: string[];
+  exports?: Record<string, unknown>;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+};
+
+const readPackage = (dir: string): PackageJson =>
+  JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as PackageJson;
+
+const forge = readPackage(FORGE_ROOT);
+
+/**
+ * Provided by the runtime, never installed: `node:` builtins, and the
+ * `cloudflare:` virtual modules workerd resolves itself (Forge's server half
+ * runs on Workers).
+ */
+const isBuiltin = (specifier: string) => specifier.startsWith("node:") || specifier.startsWith("cloudflare:");
+
+const isRelative = (specifier: string) => specifier.startsWith(".") || specifier.startsWith("/");
+
+/** `@scope/name/deep/path` and `name/deep/path` both resolve to the PACKAGE. */
+const packageNameOf = (specifier: string): string => {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!;
+};
+
+const isSpecFile = (path: string) => path.includes(`${"/"}_tests${"/"}`) || /\.(spec|test)\.[cm]?[jt]sx?$/.test(path);
+
+const sourceFiles = (dir: string, found: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      sourceFiles(full, found);
+      continue;
+    }
+    if (!/\.[cm]?[jt]sx?$/.test(full)) continue;
+    if (isSpecFile(full)) continue;
+    found.push(full);
+  }
+  return found;
+};
+
+/**
+ * The module specifiers, and only those.
+ *
+ * Anchored at a statement start and unable to cross a `;`, because a bare
+ * `/from ["']/` also matches ordinary prose in a string literal - this package
+ * has several ("gone for the next few minutes"), and each one would arrive here
+ * looking like an undeclared dependency.
+ */
+const IMPORT_PATTERNS = [
+  // `import … from "x"` / `export … from "x"`, including the multi-line form.
+  /(?:^|\n)[ \t]*(?:import|export)\s[^;]*?\bfrom\s*["']([^"']+)["']/g,
+  // Side-effect import: `import "x";`
+  /(?:^|\n)[ \t]*import\s*["']([^"']+)["']/g,
+  // `import("x")` and `require("x")`.
+  /\b(?:import|require)\s*\(\s*["']([^"']+)["']\s*\)/g,
+];
+
+const specifiersIn = (contents: string): string[] =>
+  IMPORT_PATTERNS.flatMap((pattern) => [...contents.matchAll(pattern)].map((match) => match[1]!));
+
+const importedPackages = (): Map<string, string[]> => {
+  const byPackage = new Map<string, string[]>();
+  for (const file of sourceFiles(join(FORGE_ROOT, "src"))) {
+    const contents = readFileSync(file, "utf-8");
+    for (const specifier of specifiersIn(contents)) {
+      if (isRelative(specifier) || isBuiltin(specifier)) continue;
+      const name = packageNameOf(specifier);
+      // `@tribe-nest/forge` importing itself only ever happens in a spec, but
+      // guard it anyway: a self-reference resolves through the exports map.
+      if (name === forge.name) continue;
+      const files = byPackage.get(name) ?? [];
+      files.push(file.slice(FORGE_ROOT.length + 1));
+      byPackage.set(name, files);
+    }
+  }
+  return byPackage;
+};
+
+describe("what a creator site's install has to produce", () => {
+  it("declares every package the published tree imports", () => {
+    const declared = new Set([
+      ...Object.keys(forge.dependencies ?? {}),
+      // A peer npm INSTALLS. An optional one is exactly the hole this closes:
+      // npm skips it, and the import it serves is unresolved on every site.
+      ...Object.keys(forge.peerDependencies ?? {}).filter((name) => !forge.peerDependenciesMeta?.[name]?.optional),
+    ]);
+
+    const undeclared = [...importedPackages()]
+      .filter(([name]) => !declared.has(name))
+      .map(([name, files]) => `${name} (imported by ${files[0]})`);
+
+    expect(undeclared).toEqual([]);
+  });
+
+  it("depends only on workspace packages npm will publish", () => {
+    const workspaceDeps = Object.keys(forge.dependencies ?? {}).filter((name) => name.startsWith("@tribe-nest/"));
+    // Not a vacuous pass: `./media` puts two of these in the tree, and a
+    // regression that removed them would be caught by the test above instead.
+    expect(workspaceDeps.length).toBeGreaterThan(0);
+
+    for (const name of workspaceDeps) {
+      const dir = join(PACKAGES_ROOT, name.replace("@tribe-nest/", ""));
+      expect(existsSync(dir), `${name} is not a package in packages/`).toBe(true);
+
+      const dependency = readPackage(dir);
+      // `"private": true` makes `npm publish` refuse outright, so the consumer's
+      // install 404s on a package that looks perfectly declared here.
+      expect(dependency.private, `${name} is private and can never be installed`).not.toBe(true);
+      // Its published artifact has to carry whatever its exports map points at.
+      expect(dependency.files ?? [], `${name} publishes no files`).not.toEqual([]);
+    }
+  });
+
+  it("points every entry subpath at a file that exists", () => {
+    for (const [subpath, target] of Object.entries(forge.exports ?? {})) {
+      expect(typeof target, `${subpath} has a non-string target`).toBe("string");
+      expect(existsSync(join(FORGE_ROOT, target as string)), `${subpath} -> ${target}`).toBe(true);
+    }
+  });
+
+  /**
+   * `./media` is the entry the code agent is TOLD about: it is registered in
+   * `ENTRY_SUBPATHS` in `apps/backend/src/utils/forgeManifest.ts`, so the agent
+   * writes imports against it. Dropping it from the exports map here would make
+   * every one of those imports unresolvable while the manifest went on
+   * advertising them.
+   */
+  it("still exports the media entry the Forge manifest advertises", () => {
+    expect(forge.exports?.["./media"]).toBe("./src/ui/media/index.ts");
+  });
+});

package/src/_tests/specsRunWorkspaceSource.spec.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+import { WORKSPACE_SOURCE_ALIASES } from "./workspaceAliases";
+
+/**
+ * Which ARTIFACT do these specs run?
+ *
+ * `@tribe-nest/media-client` and `@tribe-nest/media-protocol` publish an
+ * exports map whose conditions are `{ types, module, default }`, and under
+ * vitest the `default` branch wins: every spec in this package was importing
+ * `media-client/build/react/index.js`, the previous COMPILATION of the very
+ * file a change to the call UI is editing. `build/` is gitignored, so the code
+ * under test was whatever that machine last compiled.
+ *
+ * It is not theoretical. Reintroducing the historical
+ * `[...room.localPublications]` selector into `src/react/index.tsx` - the exact
+ * mutation `ui/media/_tests/CallStage.spec.tsx`'s anti-loop guard exists to
+ * catch - left all 14 of its tests green. Applying it to `build/react/index.js`
+ * turned all 14 red. The guard the whole file is built around was guarding a
+ * stale copy.
+ *
+ * A root `turbo run test` builds first (`dependsOn: ["^build"]`), so CI never
+ * saw it. The per-package `npm run test` and the watch loop - where the
+ * iteration actually happens - did.
+ *
+ * So: every workspace package this one depends on whose exports point at
+ * `build/` must be aliased to its SOURCE in `vitest.config.mts`. This test is
+ * what makes adding the next such dependency fail loudly rather than silently
+ * testing yesterday's compilation of it.
+ */
+
+const FORGE_ROOT = join(__dirname, "..", "..");
+const PACKAGES_ROOT = join(FORGE_ROOT, "..");
+
+type ExportTarget = string | Record<string, string>;
+type PackageJson = {
+  name: string;
+  exports?: Record<string, ExportTarget>;
+  dependencies?: Record<string, string>;
+};
+
+const readPackage = (dir: string): PackageJson =>
+  JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as PackageJson;
+
+const forge = readPackage(FORGE_ROOT);
+
+/** The array `vitest.config.mts` hands to `resolve.alias`, not a copy of it. */
+const aliases = () => WORKSPACE_SOURCE_ALIASES;
+
+const matches = (find: RegExp | string, specifier: string): boolean =>
+  typeof find === "string" ? specifier.startsWith(find) : find.test(specifier);
+
+/** Every subpath a package publishes, as the specifier a spec would import. */
+const subpathSpecifiers = (pkg: PackageJson): { specifier: string; target: ExportTarget }[] =>
+  Object.entries(pkg.exports ?? {}).map(([subpath, target]) => ({
+    specifier: subpath === "." ? pkg.name : `${pkg.name}/${subpath.replace(/^\.\//, "")}`,
+    target,
+  }));
+
+/** Does resolving this entry land in a compiled artifact rather than in `src`? */
+const resolvesToBuild = (target: ExportTarget): boolean => {
+  const candidate = typeof target === "string" ? target : target.default;
+  return typeof candidate === "string" && candidate.includes("build/");
+};
+
+describe("the specs in this package run the source, not a stale build", () => {
+  const workspaceDeps = Object.keys(forge.dependencies ?? {}).filter((name) => name.startsWith("@tribe-nest/"));
+
+  it("has workspace dependencies to check, so this is not vacuous", () => {
+    expect(workspaceDeps.length).toBeGreaterThan(0);
+  });
+
+  it("is the list the runner actually uses", () => {
+    // Read as TEXT because `tsc` refuses an import path ending in `.mts`. The
+    // point is that the array asserted below is the one wired into
+    // `resolve.alias`, and not a module the config stopped importing.
+    const config = readFileSync(join(FORGE_ROOT, "vitest.config.mts"), "utf-8");
+    expect(config).toContain("WORKSPACE_SOURCE_ALIASES");
+    expect(config).toMatch(/resolve:\s*{\s*alias:\s*WORKSPACE_SOURCE_ALIASES/);
+  });
+
+  it("aliases every build-first workspace entry point to its source", () => {
+    const unaliased: string[] = [];
+
+    for (const name of workspaceDeps) {
+      const dir = join(PACKAGES_ROOT, name.replace("@tribe-nest/", ""));
+      if (!existsSync(dir)) continue;
+
+      for (const { specifier, target } of subpathSpecifiers(readPackage(dir))) {
+        if (!resolvesToBuild(target)) continue;
+        if (!aliases().some((alias) => matches(alias.find, specifier))) unaliased.push(specifier);
+      }
+    }
+
+    expect(unaliased).toEqual([]);
+  });
+
+  it("points every alias at a file that exists", () => {
+    for (const alias of aliases()) {
+      expect(existsSync(alias.replacement), `${String(alias.find)} -> ${alias.replacement}`).toBe(true);
+      expect(alias.replacement, `${String(alias.find)} is aliased to a build artifact`).not.toContain("/build/");
+    }
+  });
+
+  it("does not let the bare package alias swallow its own subpaths", () => {
+    // `{ find: "@tribe-nest/media-client" }` as a plain string is a PREFIX
+    // match, so it would rewrite `@tribe-nest/media-client/react` to
+    // `.../src/index.ts/react`. Anchored patterns are what keep the subpaths
+    // reachable, and this is the mistake that silently un-does the fix above.
+    const bare = aliases().find((alias) => matches(alias.find, "@tribe-nest/media-client"));
+    expect(bare, "media-client has no alias at all").toBeDefined();
+    expect(matches(bare!.find, "@tribe-nest/media-client/react")).toBe(false);
+  });
+});

package/src/_tests/workspaceAliases.ts

@@ -0,0 +1,40 @@
+import { fileURLToPath } from "node:url";
+
+/**
+ * Which ARTIFACT the specs in this package run.
+ *
+ * `@tribe-nest/media-client` and `@tribe-nest/media-protocol` publish an
+ * exports map whose conditions are `{ types, module, default }`, and under
+ * vitest the `default` branch wins: every spec here was importing
+ * `media-client/build/react/index.js`, the previous COMPILATION of the very
+ * file a change to the call UI edits. `build/` is gitignored, so the code under
+ * test was whatever that machine last compiled.
+ *
+ * It is not theoretical. Reintroducing the historical
+ * `[...room.localPublications]` selector into `media-client/src/react/index.tsx`
+ * - the exact mutation `ui/media/_tests/CallStage.spec.tsx`'s anti-loop guard
+ * exists to catch - left all 14 of its tests green. Applying the same edit to
+ * `build/react/index.js` turned all 14 red.
+ *
+ * A root `turbo run test` builds first (`dependsOn: ["^build"]`), so CI never
+ * saw it; the per-package `npm run test` and the watch loop, where the
+ * iteration actually happens, did.
+ *
+ * Lives in `src/` rather than beside the config because `vitest.config.mts`
+ * cannot be imported from a spec (`tsc` refuses a `.mts` import path), and
+ * `specsRunWorkspaceSource.spec.ts` has to read the same list the runner uses
+ * or it is checking its own copy.
+ */
+
+/** Exact-match patterns, so the bare package does not swallow its subpaths. */
+export const WORKSPACE_SOURCE_ALIASES: { find: RegExp; replacement: string }[] = [
+  ["@tribe-nest/media-client", "../../../media-client/src/index.ts"],
+  ["@tribe-nest/media-client/react", "../../../media-client/src/react/index.tsx"],
+  ["@tribe-nest/media-client/core", "../../../media-client/src/core/index.ts"],
+  ["@tribe-nest/media-client/protocol", "../../../media-client/src/protocol.ts"],
+  ["@tribe-nest/media-protocol", "../../../media-protocol/src/index.ts"],
+  ["@tribe-nest/media-protocol/token", "../../../media-protocol/src/token.ts"],
+].map(([specifier, path]) => ({
+  find: new RegExp(`^${specifier!.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")}$`),
+  replacement: fileURLToPath(new URL(path!, import.meta.url)),
+}));

package/src/client/_tests/localeHeader.spec.tsx

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { AxiosRequestConfig } from "axios";
+import { createForgeClient } from "../createForgeClient";
+import { getSiteLocale, setSiteLocale } from "../activeLocale";
+import { SiteConfigProvider } from "../../provider/SiteConfigProvider";
+import type { SiteConfig } from "../../data/queries/useWebsite";
+
+/**
+ * The last link in the chain that lets a German site be German all the way down:
+ * the tenant's locale rides every API request as `x-locale`, which the backend
+ * reads into its request store and answers in.
+ *
+ * The failure this guards against is quiet. Nothing errors when the header is
+ * missing: the page renders German, the API answers English, and the only
+ * person who notices is the visitor who gets told "Product not found" on an
+ * otherwise German checkout.
+ */
+
+// Captures the outgoing config without a network round trip. The request
+// interceptor has already run by the time the adapter is called, so whatever
+// lands here is exactly what would have gone over the wire.
+function clientCapturingHeaders() {
+  const sent: AxiosRequestConfig[] = [];
+  const client = createForgeClient({ baseURL: "https://api.example.test" });
+  client.defaults.adapter = async (config) => {
+    sent.push(config);
+    return { data: {}, status: 200, statusText: "OK", headers: {}, config } as never;
+  };
+  return { client, sent };
+}
+
+describe("x-locale on every Forge request", () => {
+  beforeEach(() => {
+    setSiteLocale(null);
+  });
+
+  it("sends nothing before any site config has been seen", async () => {
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-locale"]).toBeUndefined();
+  });
+
+  it("sends the tenant's locale once it is known", async () => {
+    setSiteLocale("de");
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-locale"]).toBe("de");
+  });
+
+  // The locale is read per request rather than captured when the client is
+  // built: the client is created once, before any site config exists.
+  it("picks up a locale set after the client was created", async () => {
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    setSiteLocale("de");
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-locale"]).toBeUndefined();
+    expect(sent[1].headers?.["x-locale"]).toBe("de");
+  });
+
+  it("leaves the other tenant headers alone", async () => {
+    setSiteLocale("de");
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-timezone-offset"]).toBeDefined();
+  });
+});
+
+describe("the site config publishes the locale to the client", () => {
+  beforeEach(() => {
+    setSiteLocale(null);
+  });
+
+  // Mounted by every site through TribeNestApp, which is what makes the header
+  // arrive on a Forge upgrade alone, with no edit to a tenant's __root.tsx.
+  it("SiteConfigProvider sets it during render, before any child can fetch", () => {
+    renderToStaticMarkup(
+      <SiteConfigProvider initialConfig={{ locale: "de" } as SiteConfig}>
+        <span>{getSiteLocale()}</span>
+      </SiteConfigProvider>,
+    );
+    expect(getSiteLocale()).toBe("de");
+  });
+
+  // An older backend returns a config with no `locale` at all, and a failed SSR
+  // bootstrap returns no config. Both mean English, which is what an absent
+  // header already gets.
+  it("clears the locale when the config carries none", () => {
+    setSiteLocale("de");
+    renderToStaticMarkup(
+      <SiteConfigProvider initialConfig={{} as SiteConfig}>
+        <span />
+      </SiteConfigProvider>,
+    );
+    expect(getSiteLocale()).toBeNull();
+  });
+});

package/src/client/activeLocale.ts

@@ -0,0 +1,34 @@
+// The language the site is being served in, held outside React so the shared
+// axios client can read it.
+//
+// Why this exists: without it a German site renders German and every error the
+// API returns arrives in English, which is the failure the visitor sees rather
+// than the one the creator configured. The backend already reads an `x-locale`
+// header into its request store (`LOCALE_HEADER_KEY`), so the whole fix is
+// getting the tenant's locale onto every request.
+//
+// Why a module singleton rather than a prop threaded to `createForgeClient`:
+// the client is created once, per `apiUrl`, before any site config is known,
+// and the locale arrives later with the site config. The same reasoning as
+// `activeFunnel` applies too: put it in the transport and no call site can
+// forget it.
+//
+// Scope: one locale at a time. One deploy serves one tenant, so on the server
+// every request writes the same value, and a creator changing the setting is
+// picked up on the next SSR render.
+
+let siteLocale: string | null = null;
+
+/**
+ * Set the language every subsequent API request declares. Called with
+ * `siteConfig.locale` where the config enters the tree, so an existing site
+ * gains the header from a Forge upgrade with no edit to its `__root.tsx`.
+ */
+export function setSiteLocale(locale: string | null | undefined): void {
+  siteLocale = locale || null;
+}
+
+/** The active site locale, or null before any site config has been seen. */
+export function getSiteLocale(): string | null {
+  return siteLocale;
+}

package/src/client/createForgeClient.ts

@@ -1,5 +1,6 @@
 import axios, { type AxiosError, type AxiosInstance } from "axios";
 import { getActiveFunnelId } from "./activeFunnel";
+import { getSiteLocale } from "./activeLocale";
 
 /**
  * Access-token refresh (backend §7 cutover). Access tokens live ~15 minutes;
@@ -69,6 +70,18 @@ export const createForgeClient = ({
       config.headers["x-funnel-id"] = funnelId;
     }
 
+    // The tenant's language, so the API answers in the language the page is
+    // written in. Without it a German site renders German and every validation
+    // message, error and generated string comes back English. The backend reads
+    // this header into its request store, so it covers everything a request
+    // touches rather than the endpoints someone remembered to translate.
+    // Absent until the site config has been seen, and the backend defaults to
+    // English on an absent or unrecognised value.
+    const locale = getSiteLocale();
+    if (locale) {
+      config.headers["x-locale"] = locale;
+    }
+
     const token = getToken?.();
     if (token) {
       config.headers["authorization"] = `Bearer ${token}`;

package/src/contexts/CartContext.tsx

@@ -106,6 +106,35 @@ interface CartContextType {
   addToCart: (item: CartItem) => boolean;
   removeFromCart: (productId: string, isGift: boolean, recipientEmail?: string) => void;
   clearCart: () => void;
+  /**
+   * Put a whole basket back at once, MERGING with whatever is already there.
+   *
+   * Built for the recovery link (`/i/checkout/resume`), where the buyer arrives
+   * from an email with lines the server has just re-priced. It exists rather
+   * than a loop over `addToCart` for two reasons, both of which produced wrong
+   * baskets when tried:
+   *
+   * - `addToCart` reads `cartItems` from its closure, so a loop decides
+   *   "already in the cart?" against a snapshot that is one render old. A
+   *   restored line matching one the visitor already had appended a DUPLICATE
+   *   instead of replacing it. This merges inside a functional update, so every
+   *   line is matched against the real current state.
+   * - Restoring must not pop the drawer open per line. The resume page IS the
+   *   surface; a drawer sliding over it is noise.
+   *
+   * MERGE, not replace: a visitor who put something in their basket between the
+   * email and the click keeps it. The restored line wins on a collision,
+   * because it is the one that was just re-priced.
+   *
+   * Tickets merge PER TIER, not per event. An event's selection is a map, and
+   * treating it as one value threw away every tier the visitor had picked in
+   * this session the moment the resumed basket named the same event. On a tier
+   * both sides name, the restored quantity REPLACES the session's rather than
+   * adding to it, matching how a colliding product line is replaced whole: both
+   * sides describe the same intent at different prices, and the resumed one is
+   * the figure the server has just re-checked.
+   */
+  restoreCart: (input: { items?: CartItem[]; tickets?: TicketCartItem[] }) => void;
   /** Ticket selections, one entry per event. */
   ticketItems: TicketCartItem[];
   /** Add or replace the selection for an event (the modal always sends the whole map). */
@@ -232,6 +261,52 @@ export function CartProvider({ children }: { children: ReactNode }) {
     );
   };
 
+  /** The identity of a product line, as `addToCart` already defines it. */
+  const lineKey = (item: CartItem) =>
+    `${item.productId}|${item.productVariantId}|${item.isGift}|${item.recipientEmail ?? ""}`;
+
+  const restoreCart = useCallback((input: { items?: CartItem[]; tickets?: TicketCartItem[] }) => {
+    const items = input.items ?? [];
+    const tickets = input.tickets ?? [];
+
+    if (items.length > 0) {
+      setCartItems((prev) => {
+        const incoming = new Map(items.map((item) => [lineKey(item), item]));
+        const merged = prev.map((item) => incoming.get(lineKey(item)) ?? item);
+        const seen = new Set(prev.map(lineKey));
+        return [...merged, ...items.filter((item) => !seen.has(lineKey(item)))];
+      });
+    }
+
+    if (tickets.length > 0) {
+      setTicketItems((prev) => {
+        const byEvent = new Map(prev.map((ticket) => [ticket.eventId, ticket]));
+        for (const incoming of tickets) {
+          const existing = byEvent.get(incoming.eventId);
+          byEvent.set(
+            incoming.eventId,
+            existing
+              ? {
+                  ...existing,
+                  ...incoming,
+                  // Tier by tier, so a tier only the session knows about
+                  // survives and a tier both name takes the resumed quantity.
+                  tickets: { ...existing.tickets, ...incoming.tickets },
+                  ticketMeta: { ...existing.ticketMeta, ...incoming.ticketMeta },
+                  // A resumed payload predating booking fees carries none, and
+                  // an absent fee must not erase the one the modal captured.
+                  bookingFee: incoming.bookingFee ?? existing.bookingFee ?? null,
+                }
+              : incoming,
+          );
+        }
+        // Insertion order: the events already in the basket keep their place,
+        // and events only the recovery link knows about go on the end.
+        return [...byEvent.values()];
+      });
+    }
+  }, []);
+
   const setTickets = useCallback((item: TicketCartItem) => {
     setTicketItems((prev) => [...prev.filter((t) => t.eventId !== item.eventId), item]);
     setCartOpen(true);
@@ -275,6 +350,7 @@ export function CartProvider({ children }: { children: ReactNode }) {
         addToCart,
         removeFromCart,
         clearCart,
+        restoreCart,
         ticketItems,
         setTickets,
         removeTickets,