@tribe-nest/forge 3.53.0 → 3.54.0

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

@@ -0,0 +1,109 @@
+import type { IEvent, ITicket } from "../../../types/models";
+
+/**
+ * Ticket requests (curated access, feature 3): the pure decisions behind the
+ * picker and the checkout, kept out of the hook so they can be tested without
+ * standing up the providers the hook needs.
+ *
+ * A tier with `requiresApproval` is not sold, it is REQUESTED: the card is
+ * committed (authorised) and the seat held, and the organiser has a window to
+ * approve or decline. One order is either a request or a purchase, never
+ * both: the API refuses a mixed cart (`errors.event.mixed_approval_cart`), and
+ * the picker stops the fan building one in the first place.
+ */
+
+/** Does this tier need the organiser's approval? Absent on an older API build means no. */
+export function tierRequiresApproval(ticket: Pick<ITicket, "requiresApproval"> | undefined): boolean {
+  return ticket?.requiresApproval === true;
+}
+
+/** Does this event carry any approval-required tier at all? Read off the tiers, not the flag, so a partial payload still answers. */
+export function eventHasApprovalTiers(event: Pick<IEvent, "tickets" | "hasApprovalTiers"> | undefined): boolean {
+  if (!event) return false;
+  if (event.hasApprovalTiers === true) return true;
+  return (event.tickets ?? []).some(tierRequiresApproval);
+}
+
+/**
+ * Which kind of order the current selection would make. `null` while nothing
+ * is selected (either kind is still addable), `"request"` once an approval
+ * tier is in, `"purchase"` once an ordinary one is. A mixed selection cannot
+ * arise through `tierBlockedByApprovalMix`, but if one is handed in (a stale
+ * cache, a tier that changed mode underneath the fan) it reads as a request,
+ * because that is the button the server will refuse rather than the one it
+ * will silently sell.
+ */
+export function selectionMode(
+  tickets: readonly Pick<ITicket, "id" | "requiresApproval">[],
+  quantities: Record<string, number>,
+): "request" | "purchase" | null {
+  let approval = false;
+  let ordinary = false;
+  for (const ticket of tickets) {
+    if ((quantities[ticket.id] ?? 0) <= 0) continue;
+    if (tierRequiresApproval(ticket)) approval = true;
+    else ordinary = true;
+  }
+  if (approval) return "request";
+  if (ordinary) return "purchase";
+  return null;
+}
+
+/** The selection contains at least one approval tier, so submitting it lodges a request. */
+export function selectionRequiresApproval(
+  tickets: readonly Pick<ITicket, "id" | "requiresApproval">[],
+  quantities: Record<string, number>,
+): boolean {
+  return selectionMode(tickets, quantities) === "request";
+}
+
+/**
+ * May this tier be added to the current selection?
+ *
+ * Blocked when the selection already holds the OTHER kind: an approval tier
+ * beside a purchase, or a purchase beside a request. A tier that is already in
+ * the selection is never blocked (it is the kind that set the mode), and an
+ * empty selection blocks nothing.
+ */
+export function tierBlockedByApprovalMix(
+  ticket: Pick<ITicket, "id" | "requiresApproval">,
+  tickets: readonly Pick<ITicket, "id" | "requiresApproval">[],
+  quantities: Record<string, number>,
+): boolean {
+  if ((quantities[ticket.id] ?? 0) > 0) return false;
+  const mode = selectionMode(tickets, quantities);
+  if (mode === null) return false;
+  return tierRequiresApproval(ticket) ? mode === "purchase" : mode === "request";
+}
+
+/** The fields of a `POST /public/events/:id/orders` response the routing reads. */
+export interface TicketOrderRoutingInput {
+  isFreeCheckout?: boolean;
+  awaitingApproval?: boolean;
+  totalAmount?: number | string | null;
+}
+
+/**
+ * Where the checkout goes once the order row exists.
+ *
+ *   complete  nothing to pay: a free purchase (passes minted, `isFreeCheckout`)
+ *             or a FREE REQUEST (already `pending_approval`, `isFreeCheckout`
+ *             false, `awaitingApproval` true, total 0). Both hand the order id
+ *             to `onComplete`, and the host navigates to the finalise page,
+ *             which renders the right outcome off the order's own status.
+ *   payment   there is money on it: start the charge. A priced request runs
+ *             the payment step exactly as a sale does; only the wording and
+ *             the settlement differ, and start-payment says which.
+ *
+ * `isFreeCheckout` wins outright, as it always has. The free-request branch is
+ * keyed on the TOTAL, not on `awaitingApproval` alone, because a priced
+ * request also carries `awaitingApproval: true` and must still reach the card.
+ */
+export function nextStepAfterTicketOrder(order: TicketOrderRoutingInput): "complete" | "payment" {
+  if (order.isFreeCheckout) return "complete";
+  if (order.awaitingApproval === true) {
+    const total = Number(order.totalAmount ?? 0);
+    if (!Number.isFinite(total) || total <= 0) return "complete";
+  }
+  return "payment";
+}

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

@@ -22,6 +22,12 @@ import { checkoutAmounts, isPayWhatYouWant, resolveUnitPrice, ticketSubtotals }
 import { parseMembershipGateError, type MembershipGateRefusal } from "../../format/membershipGate";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
+import {
+  eventHasApprovalTiers,
+  nextStepAfterTicketOrder,
+  selectionRequiresApproval,
+  tierBlockedByApprovalMix,
+} from "./ticketApproval";
 
 export type EventCheckoutStep = "tickets" | "details" | "payment";
 
@@ -32,7 +38,10 @@ export interface UseEventCheckoutOptions {
   finalisePath?: (slug: string, orderId: string) => string;
   /** Called when a FREE order completes in-app — the host navigates however it
    * wants (e.g. its router), instead of Forge doing a `window.location` redirect.
-   * Omit to keep the default redirect. */
+   * Omit to keep the default redirect. Also fired for a FREE TICKET REQUEST
+   * (`awaitingApproval` with nothing to pay), which has no payment step either:
+   * the finalise page it lands on reads the order's status and renders
+   * "request received". */
   onComplete?: (info: { slug: string; orderId: string }) => void;
 }
 
@@ -179,6 +188,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     [selectedTickets],
   );
 
+  /**
+   * Ticket requests (curated access, feature 3).
+   *
+   * `hasApprovalTiers` says the event carries one at all; `awaitingApproval`
+   * says THIS selection is a request rather than a purchase, which is what the
+   * primary button ("Request tickets") and the payment wording read. One order
+   * is either, never both: `isTierBlockedByApprovalMix` is what the picker
+   * disables the `+` on, so the server's mixed-cart refusal is never reached.
+   */
+  const hasApprovalTiers = eventHasApprovalTiers(event);
+  const awaitingApproval = useMemo(
+    () => selectionRequiresApproval(event?.tickets ?? [], selectedTickets),
+    [event, selectedTickets],
+  );
+  const isTierBlockedByApprovalMix = (ticketId: string) => {
+    const ticket = event?.tickets.find((t) => t.id === ticketId);
+    return ticket ? tierBlockedByApprovalMix(ticket, event?.tickets ?? [], selectedTickets) : false;
+  };
+  /** When the request lapses if the organiser does not decide, from the order response. */
+  const [requestExpiresAt, setRequestExpiresAt] = useState<string | null>(null);
+
   /**
    * The artist's booking fee (1.4) — the thing the buyer was charged and never
    * told about, on any surface, on either rendering stack.
@@ -212,6 +242,13 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   // rejects those with "quantity must be positive").
   const setTicketQty = (ticketId: string, qty: number) =>
     setSelectedTickets((prev) => {
+      // A request and a purchase cannot share an order. The picker disables
+      // the control, and this refuses the write too, so a host that drives the
+      // hook from its own UI cannot build the cart the server will refuse.
+      if (qty > 0 && (prev[ticketId] ?? 0) === 0 && event) {
+        const ticket = event.tickets.find((t) => t.id === ticketId);
+        if (ticket && tierBlockedByApprovalMix(ticket, event.tickets, prev)) return prev;
+      }
       const next = { ...prev };
       if (qty > 0) next[ticketId] = qty;
       else delete next[ticketId];
@@ -253,6 +290,14 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       return false;
     }
     if (!event) return false;
+    // A request is not a purchase and cannot ride in a bundle: the bundle
+    // checkout forces payment and the API refuses approval tiers in one. Sent
+    // to the cart it would fail at the end of a longer journey, so it is
+    // refused here, and the surface hides the exit for a request anyway.
+    if (awaitingApproval) {
+      setError("Tickets that need our approval are requested on their own.");
+      return false;
+    }
     setError(null);
     setTickets({
       eventId: event.id,
@@ -372,12 +417,15 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       // legitimately reports 0 — falling back to the estimate there would put a
       // fee on a comp.
       setServerFeeAmount(data.feeAmount ?? 0);
+      setRequestExpiresAt(data.requestExpiresAt ?? null);
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, data.orderId)}`;
       setReturnUrl(ru);
-      if (data.isFreeCheckout) {
-        // Free order — no payment. Hand navigation to the host if it asked, else
-        // default to an in-app redirect to the finalise page.
+      if (nextStepAfterTicketOrder(data) === "complete") {
+        // Nothing to pay: a free order, or a free ticket REQUEST that is already
+        // `pending_approval`. Hand navigation to the host if it asked, else
+        // default to an in-app redirect to the finalise page, which renders the
+        // right outcome off the order's own status.
         if (opts.onComplete) opts.onComplete({ slug, orderId: data.orderId });
         else if (typeof window !== "undefined") window.location.href = ru;
         return;
@@ -436,6 +484,7 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     // subtotal, so keeping it would understate the fee on the fresh, full-price
     // order the next `continueToPayment` creates.
     setServerFeeAmount(null);
+    setRequestExpiresAt(null);
     setStep("details");
   };
 
@@ -493,6 +542,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     /** What each selected PWYW tier will actually be charged, per unit. */
     effectiveAmounts,
     ticketCount,
+    /**
+     * Ticket requests (curated access, feature 3). `hasApprovalTiers`: the
+     * event carries at least one tier the organiser approves. `awaitingApproval`:
+     * THIS selection is a request, so the primary button reads "Request
+     * tickets", the pay button "Authorize", and nothing is sold until the
+     * organiser decides. `isTierBlockedByApprovalMix(id)`: the tier cannot join
+     * the current selection because one order is either a request or a
+     * purchase, never both. `requestExpiresAt`: when an undecided request
+     * lapses, once the order exists.
+     */
+    hasApprovalTiers,
+    awaitingApproval,
+    isTierBlockedByApprovalMix,
+    requestExpiresAt,
+    /**
+     * From start-payment: `"deferred"` on a priced request, so the payment
+     * renderer can label the button "Authorize" and say the card is charged
+     * only on approval. Undefined on a sale.
+     */
+    settlement: flow.settlement,
+    deferredStrategy: flow.deferredStrategy,
     // 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
     // the locally summed ticket prices before either exists.

package/src/ui/headless/index.ts

@@ -53,6 +53,17 @@ export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 // Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
 export { useEventCheckout, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+// Ticket requests (curated access): the pure decisions behind the picker and
+// the post-order routing, for a host that drives the hook from its own UI.
+export {
+  eventHasApprovalTiers,
+  nextStepAfterTicketOrder,
+  selectionMode,
+  selectionRequiresApproval,
+  tierBlockedByApprovalMix,
+  tierRequiresApproval,
+  type TicketOrderRoutingInput,
+} from "./event/ticketApproval";
 export {
   usePresaleCode,
   type PresaleCodeField,

package/src/ui/index.ts

@@ -73,6 +73,15 @@ export {
 export { PresaleCodeField, type PresaleCodeFieldProps } from "./styled/PresaleCode";
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
+// For a custom payment renderer: which post-confirm statuses count as done
+// (a deferred charge stops at `requires_capture`), and the deferred-charge
+// wording decision the built-in renderer makes.
+export {
+  deferredChargeNotice,
+  isDeferredSettlement,
+  isManualConfirmSuccess,
+  MANUAL_CONFIRM_SUCCESS_STATUSES,
+} from "./payment/stripeConfirmOutcome";
 export { Cart, type CartProps } from "./styled/Cart";
 /** The page a cart-recovery email lands on. Drop in at `/i/checkout/resume`. */
 export { ResumeCart, type ResumeCartProps } from "./styled/ResumeCart";
@@ -346,3 +355,12 @@ export * from "./styled/work";
 
 // Unified member home (`/i/members`) styled blocks.
 export * from "./styled/members";
+
+// The review page a "how did we do?" email lands on. Here rather than in a
+// storefront because both the hosted `/i/reviews/$token` page and every site's
+// root-level `/reviews/$token` alias render it.
+export * from "./styled/ReviewRequestPage";
+// The contract signing page. Here for the same reason: both storefronts render
+// it, at BOTH the canonical `/i/documents/$token` and the older
+// `/documents/$token` that already-sent links point at.
+export * from "./styled/DocumentSigningPage";

package/src/ui/payment/ForgePaymentProvider.tsx

@@ -1,3 +1,4 @@
+import type { DeferredChargeStrategy, PaymentSettlement } from "../../types/models";
 import { createContext, useContext, type ReactNode } from "react";
 import { ForgeStripePayment } from "./ForgeStripePayment";
 
@@ -16,6 +17,20 @@ export interface PaymentRenderProps {
   mode?: "redirect" | "manual";
   onSucceeded?: () => void;
   onFailed?: (message?: string) => void;
+  /**
+   * `"deferred"` when the charge is committed now and taken only if the
+   * organiser approves (a ticket request). The built-in renderer then labels
+   * the button "Authorize {amount}" and says under it that the card is charged
+   * only on approval. Absent on every ordinary sale, so a custom renderer that
+   * ignores it keeps working exactly as before.
+   */
+  settlement?: PaymentSettlement;
+  /**
+   * How the provider defers: `"authorization"` shows a temporary hold on the
+   * fan's statement and the renderer says so; `"saved_instrument"` takes
+   * nothing until approval. Only sent with `settlement: "deferred"`.
+   */
+  deferredStrategy?: DeferredChargeStrategy | null;
 }
 
 export type PaymentRenderer = (props: PaymentRenderProps) => ReactNode;

package/src/ui/payment/ForgeStripePayment.tsx

@@ -5,7 +5,9 @@ import { useForgeTheme } from "../theme/ForgeThemeProvider";
 import { readableTextOn } from "../theme/contrast";
 import { useFormatCurrency } from "../format/useFormatCurrency";
 import { useSiteConfig } from "../../data/queries/useWebsite";
+import { useForgeT } from "../../i18n";
 import type { PaymentRenderProps } from "./ForgePaymentProvider";
+import { deferredChargeNotice, isDeferredSettlement, isManualConfirmSuccess } from "./stripeConfirmOutcome";
 
 function alpha(hex: number) {
   return Math.round(hex * 255)
@@ -30,6 +32,8 @@ export function ForgeStripePayment({
   mode = "redirect",
   onSucceeded,
   onFailed,
+  settlement,
+  deferredStrategy,
 }: PaymentRenderProps) {
   const theme = useForgeTheme();
   const { data: siteConfig } = useSiteConfig();
@@ -91,7 +95,16 @@ export function ForgeStripePayment({
 
   return (
     <Elements options={{ clientSecret, appearance, loader: "auto" }} stripe={stripePromise}>
-      <Inner returnUrl={returnUrl} amount={amount} currency={currency} mode={mode} onSucceeded={onSucceeded} onFailed={onFailed} />
+      <Inner
+        returnUrl={returnUrl}
+        amount={amount}
+        currency={currency}
+        mode={mode}
+        onSucceeded={onSucceeded}
+        onFailed={onFailed}
+        settlement={settlement}
+        deferredStrategy={deferredStrategy}
+      />
     </Elements>
   );
 }
@@ -103,15 +116,26 @@ function Inner({
   mode = "redirect",
   onSucceeded,
   onFailed,
+  settlement,
+  deferredStrategy,
 }: Omit<PaymentRenderProps, "clientSecret">) {
   const theme = useForgeTheme();
+  const t = useForgeT();
   const { formatCurrency } = useFormatCurrency();
   const stripe = useStripe();
   const elements = useElements();
   const [message, setMessage] = useState("");
   const [isLoading, setIsLoading] = useState(false);
 
-  const buttonText = `Pay ${formatCurrency(amount, currency || undefined)} Now`;
+  // A deferred charge is not a payment yet: the button says what actually
+  // happens when it is pressed, and the line under it says when the money
+  // moves. That line is content, not help: a fan reading "Authorize" without
+  // it has been told their card was committed and nothing about why.
+  const deferred = isDeferredSettlement(settlement);
+  const formattedAmount = formatCurrency(amount, currency || undefined);
+  const buttonText = deferred
+    ? t("forge.forge_stripe_payment.authorize", { amount: formattedAmount })
+    : `Pay ${formattedAmount} Now`;
 
   const handleSubmit = useCallback(async () => {
     if (!stripe || !elements) return;
@@ -131,7 +155,9 @@ function Inner({
         onFailed?.(msg);
         return;
       }
-      if (paymentIntent?.status === "succeeded" || paymentIntent?.status === "processing") {
+      // `requires_capture` is a deferred charge that went through: the card is
+      // authorised and the platform captures it on approval. See the helper.
+      if (isManualConfirmSuccess(paymentIntent?.status)) {
         setIsLoading(false);
         onSucceeded?.();
         return;
@@ -166,6 +192,14 @@ function Inner({
       >
         {isLoading ? "Processing…" : buttonText}
       </button>
+      {deferred && (
+        <p data-testid="deferred-charge-notice" style={{ margin: 0, fontSize: 13, opacity: 0.8, lineHeight: 1.5 }}>
+          {t("forge.forge_stripe_payment.deferred_charged_on_approval")}
+          {deferredChargeNotice(deferredStrategy) === "authorization" && (
+            <> {t("forge.forge_stripe_payment.deferred_hold_on_statement")}</>
+          )}
+        </p>
+      )}
     </form>
   );
 }

package/src/ui/payment/_tests/stripeConfirmOutcome.spec.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import {
+  deferredChargeNotice,
+  isDeferredSettlement,
+  isManualConfirmSuccess,
+  MANUAL_CONFIRM_SUCCESS_STATUSES,
+} from "../stripeConfirmOutcome";
+
+/**
+ * The one-line fix from the curated-access design (section 6.2, step 2): a
+ * deferred charge leaves the PaymentIntent at `requires_capture`, and the
+ * manual-mode branch of `ForgeStripePayment` used to read anything that was
+ * not `succeeded`/`processing` as "Payment did not complete". The decision is
+ * a pure function now, so the renderer cannot drift back.
+ */
+describe("isManualConfirmSuccess", () => {
+  it("REGRESSION: counts an authorised, uncaptured intent as the fan being done", () => {
+    expect(isManualConfirmSuccess("requires_capture")).toBe(true);
+  });
+
+  it("keeps the two statuses it always accepted", () => {
+    expect(isManualConfirmSuccess("succeeded")).toBe(true);
+    expect(isManualConfirmSuccess("processing")).toBe(true);
+  });
+
+  it("still refuses every status that means the fan is not done", () => {
+    for (const status of ["requires_payment_method", "requires_confirmation", "requires_action", "canceled"]) {
+      expect(isManualConfirmSuccess(status)).toBe(false);
+    }
+    expect(isManualConfirmSuccess(undefined)).toBe(false);
+    expect(isManualConfirmSuccess(null)).toBe(false);
+    expect(isManualConfirmSuccess("")).toBe(false);
+  });
+
+  it("exposes the same set the renderer reads, so a custom renderer can share it", () => {
+    expect([...MANUAL_CONFIRM_SUCCESS_STATUSES].sort()).toEqual(["processing", "requires_capture", "succeeded"]);
+  });
+});
+
+describe("isDeferredSettlement", () => {
+  it("is true only for an explicit deferred charge", () => {
+    expect(isDeferredSettlement("deferred")).toBe(true);
+    expect(isDeferredSettlement("immediate")).toBe(false);
+    // An older API build sends nothing, and nothing must render as a sale.
+    expect(isDeferredSettlement(undefined)).toBe(false);
+    expect(isDeferredSettlement(null)).toBe(false);
+  });
+});
+
+describe("deferredChargeNotice", () => {
+  it("promises a visible hold only when the provider actually places one", () => {
+    expect(deferredChargeNotice("authorization")).toBe("authorization");
+    expect(deferredChargeNotice("saved_instrument")).toBe("saved_instrument");
+  });
+
+  it("falls back to the quieter line for an unknown strategy", () => {
+    // Promising a hold that never appears is the larger lie of the two.
+    expect(deferredChargeNotice(undefined)).toBe("saved_instrument");
+    expect(deferredChargeNotice(null)).toBe("saved_instrument");
+  });
+});

package/src/ui/payment/stripeConfirmOutcome.ts

@@ -0,0 +1,50 @@
+import type { DeferredChargeStrategy, PaymentSettlement } from "../../types/models";
+
+/**
+ * The PaymentIntent statuses `confirmPayment` can leave behind that mean "the
+ * fan's part is done", in the manual (confirm-in-place) branch of
+ * `ForgeStripePayment`.
+ *
+ *   succeeded         charged
+ *   processing        a delayed-notification method (bank debit); charged later
+ *   requires_capture  AUTHORISED, not captured: a deferred charge. The platform
+ *                     captures it when the organiser approves a ticket request
+ *                     (curated access, feature 3) and cancels it otherwise.
+ *
+ * Before `requires_capture` was here a request checkout confirmed the card,
+ * Stripe answered exactly what a manual-capture intent answers, and the
+ * renderer told the fan "Payment did not complete" while the order was already
+ * on its way to `pending_approval`. Anything else (`requires_payment_method`,
+ * `requires_action` that did not resolve, `canceled`) is not done.
+ */
+export const MANUAL_CONFIRM_SUCCESS_STATUSES: ReadonlySet<string> = new Set([
+  "succeeded",
+  "processing",
+  "requires_capture",
+]);
+
+/** Does this post-confirm PaymentIntent status count as the fan having finished? */
+export function isManualConfirmSuccess(status: string | null | undefined): boolean {
+  return !!status && MANUAL_CONFIRM_SUCCESS_STATUSES.has(status);
+}
+
+/** A deferred charge: the card is committed now and taken only on approval. */
+export function isDeferredSettlement(settlement: PaymentSettlement | null | undefined): boolean {
+  return settlement === "deferred";
+}
+
+/**
+ * Which explanation goes under the pay button on a deferred charge.
+ *
+ * `authorization` places a hold the fan will SEE on their statement, so the
+ * line has to say so or the first thing they notice is a pending charge they
+ * were promised would not happen. `saved_instrument` (a provider that stores
+ * the card and charges it later) takes nothing, and the line says only that.
+ * An unknown strategy is treated as the quieter of the two: promising a hold
+ * that never appears is the lesser lie.
+ */
+export function deferredChargeNotice(
+  strategy: DeferredChargeStrategy | null | undefined,
+): "authorization" | "saved_instrument" {
+  return strategy === "authorization" ? "authorization" : "saved_instrument";
+}

package/src/ui/shell/TribeNestApp.tsx

@@ -16,6 +16,12 @@ import { previewDiagnosticsEnabled, resolvePreviewDiagnostics } from "./diagnost
 import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
 import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
 import { captureLandingFromUrl, postLandingBeacon } from "../../utils/landing";
+import { registerHostRuntime } from "../../runtime/hostRuntime";
+
+// Module scope, not a hook. The hosted `/i/*` bundle can be imported by the
+// very first page a visitor lands on, so the runtime it reads has to be
+// published before any component renders, not during one.
+registerHostRuntime();
 
 // Captures both attribution signals on first paint: the tracked-link `?tn_ref`
 // (stripped afterwards) and the first-touch landing snapshot (all utm/click-id