@tribe-nest/forge 3.20.0 → 3.22.0

package/src/ui/headless/calendar/_tests/useAddToCalendar.spec.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { buildAddToCalendarLinks } from "../useAddToCalendar";
+
+/**
+ * The Apple half of "add to calendar", which for a long time did not exist.
+ *
+ * Google and Microsoft publish TEMPLATE URLs — the whole event travels in the
+ * query string and no server is involved. Apple publishes nothing of the kind:
+ * Calendar takes a FILE, and Safari on iOS treats an https `.ics` as a file it
+ * cannot open. `webcal://` is the scheme iOS and macOS route to the Calendar
+ * app, so it is the only thing that makes an Apple option possible at all.
+ *
+ * This file is about the derivation, because that is where a mistake would be
+ * silent: a mangled scheme still renders a chip, and the failure only shows up
+ * on somebody's phone.
+ */
+describe("buildAddToCalendarLinks — the Apple routes", () => {
+  const base = { title: "Night Show", start: "2026-03-15T20:00:00.000Z" };
+
+  const ICS = "https://api.tribenest.co/public/calendar/events/abc/tok.ics";
+
+  it("offers neither route when the host has no .ics to point at", () => {
+    const links = buildAddToCalendarLinks(base)!;
+
+    // A site pinned to an older API build must degrade to the three template
+    // providers, not draw a dead Apple chip.
+    expect(links.ics).toBeNull();
+    expect(links.webcal).toBeNull();
+    expect(links.google).toContain("calendar.google.com");
+  });
+
+  it("derives webcal:// from the https address when only that is supplied", () => {
+    const links = buildAddToCalendarLinks({ ...base, icsUrl: ICS })!;
+
+    expect(links.ics).toBe(ICS);
+    // Scheme-only swap: the path, the id and the HMAC token must survive
+    // untouched, or the link resolves to a different document (or to nothing).
+    expect(links.webcal).toBe("webcal://api.tribenest.co/public/calendar/events/abc/tok.ics");
+  });
+
+  it("prefers the server's own webcal URL over the derivation", () => {
+    const links = buildAddToCalendarLinks({
+      ...base,
+      icsUrl: ICS,
+      webcalUrl: "webcal://cdn.example.com/other.ics",
+    })!;
+
+    // The API composes both; if it ever puts them on different hosts, the
+    // client must not quietly out-vote it.
+    expect(links.webcal).toBe("webcal://cdn.example.com/other.ics");
+  });
+
+  it("derives from http as well as https", () => {
+    const links = buildAddToCalendarLinks({ ...base, icsUrl: "http://localhost:8000/public/calendar/events/a/t.ics" })!;
+    expect(links.webcal).toBe("webcal://localhost:8000/public/calendar/events/a/t.ics");
+  });
+
+  it("refuses to invent a webcal URL from something that is not absolute", () => {
+    // `calendarFeedUrl` falls back to a bare PATH when `API_URL` is unset, and
+    // "webcal:///public/calendar/…" is not an address any client can resolve.
+    // Better no Apple option than a broken one.
+    const links = buildAddToCalendarLinks({ ...base, icsUrl: "/public/calendar/events/abc/tok.ics" })!;
+
+    expect(links.ics).toBe("/public/calendar/events/abc/tok.ics");
+    expect(links.webcal).toBeNull();
+  });
+
+  it("passes an already-webcal address through unchanged", () => {
+    const links = buildAddToCalendarLinks({ ...base, webcalUrl: "webcal://api.tribenest.co/a.ics" })!;
+    expect(links.webcal).toBe("webcal://api.tribenest.co/a.ics");
+    // No https form was supplied, so no download is offered.
+    expect(links.ics).toBeNull();
+  });
+
+  it("leaves the three template providers untouched by any of this", () => {
+    const withIcs = buildAddToCalendarLinks({ ...base, icsUrl: ICS })!;
+    const without = buildAddToCalendarLinks(base)!;
+
+    expect(withIcs.google).toBe(without.google);
+    expect(withIcs.outlook).toBe(without.outlook);
+    expect(withIcs.office365).toBe(without.office365);
+  });
+});

package/src/ui/headless/calendar/useAddToCalendar.ts

@@ -26,11 +26,29 @@ export type AddToCalendarInput = {
   /** Canonical page for the event; appended to the description body when present. */
   url?: string | null;
   /**
-   * Absolute URL to a downloadable `.ics` (what Apple Calendar / Outlook desktop
-   * want). Forge does not synthesize this — the host passes the endpoint it has.
-   * When absent, `ics` comes back `null` and no Apple option is offered.
+   * Absolute URL to a downloadable `.ics` — what Outlook desktop, Thunderbird
+   * and a Mac that would rather have the file all want.
+   *
+   * Forge does not synthesize this and cannot: the platform's `.ics` address
+   * carries a keyed HMAC, so it is deliberately not derivable from an event id.
+   * The host passes the field the API gave it (`calendarUrl`). When absent,
+   * `ics` comes back `null` and no download option is offered.
    */
   icsUrl?: string | null;
+  /**
+   * The same `.ics`, under `webcal://` — the API's `calendarWebcalUrl`.
+   *
+   * **This is the Apple route, and there is no other.** Apple publishes no
+   * "add to calendar" template URL the way Google and Microsoft do, which is
+   * exactly why every control in this product used to offer three providers and
+   * no Apple option. Safari on iOS treats an https `.ics` as a file it cannot
+   * open; the same address under `webcal:` is handed straight to Calendar.
+   *
+   * Optional, and derived from {@link icsUrl} when omitted — a host on an older
+   * API build that only carries the https form still gets a working Apple
+   * option, because the two differ only by scheme.
+   */
+  webcalUrl?: string | null;
 };
 
 export type AddToCalendarLinks = {
@@ -42,8 +60,14 @@ export type AddToCalendarLinks = {
   office365: string;
   /** Yahoo Calendar. */
   yahoo: string;
-  /** Pass-through of `icsUrl` — the Apple/desktop route. `null` when not supplied. */
+  /** Pass-through of `icsUrl` — the download route. `null` when not supplied. */
   ics: string | null;
+  /**
+   * The `webcal://` address, for the Apple option. Falls back to `icsUrl` with
+   * its scheme swapped, so supplying either one is enough. `null` when neither
+   * is available.
+   */
+  webcal: string | null;
   startsAt: Date;
   endsAt: Date;
 };
@@ -97,6 +121,20 @@ export function stripHtml(html: string, maxLength: number = MAX_DESCRIPTION_CHAR
 
 const enc = encodeURIComponent;
 
+/**
+ * The `webcal://` form, preferring what the host was given.
+ *
+ * The swap is scheme-only and is applied to an https address, never to an
+ * arbitrary string: a relative or already-`webcal:` URL is passed through
+ * untouched rather than being mangled into something a calendar client would
+ * refuse.
+ */
+function toWebcal(webcalUrl?: string | null, icsUrl?: string | null): string | null {
+  if (webcalUrl) return webcalUrl;
+  if (!icsUrl) return null;
+  return /^https?:\/\//i.test(icsUrl) ? icsUrl.replace(/^https?:\/\//i, "webcal://") : null;
+}
+
 /**
  * Build every provider URL for one calendar entry. Returns `null` when the
  * start is missing or unparseable — callers render nothing rather than a link
@@ -156,6 +194,7 @@ export function buildAddToCalendarLinks(input: AddToCalendarInput): AddToCalenda
       `&desc=${enc(body)}` +
       `&in_loc=${enc(location)}`,
     ics: input.icsUrl || null,
+    webcal: toWebcal(input.webcalUrl, input.icsUrl),
     startsAt,
     endsAt,
   };
@@ -177,6 +216,7 @@ export function useAddToCalendar(input: AddToCalendarInput | null | undefined):
   const location = input?.location;
   const url = input?.url;
   const icsUrl = input?.icsUrl;
+  const webcalUrl = input?.webcalUrl;
 
   return useMemo(() => {
     if (!start) return null;
@@ -189,6 +229,7 @@ export function useAddToCalendar(input: AddToCalendarInput | null | undefined):
       location,
       url,
       icsUrl,
+      webcalUrl,
     });
-  }, [title, start, end, defaultDurationMinutes, description, location, url, icsUrl]);
+  }, [title, start, end, defaultDurationMinutes, description, location, url, icsUrl, webcalUrl]);
 }

package/src/ui/headless/checkout/_tests/inventoryHold.spec.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import {
+  HOLD_EXPIRED_CODE,
+  formatHoldRemaining,
+  holdExpiredMessage,
+  holdMsRemaining,
+  isHoldExpiredError,
+} from "../inventoryHold";
+
+/**
+ * The inventory hold, as both rendering stacks read it.
+ *
+ * Every case here is a bug the checkout shipped with before this existed: a
+ * buyer told "sold out" for an item that was not sold out, a countdown drawn
+ * over an order that had no reservation at all, and a timer that read "0:00"
+ * for a whole second while the payment was still perfectly good.
+ *
+ * Pure, so they run with no provider tree — the same reason `bundleCoupon`'s
+ * helpers live outside the hook.
+ */
+
+const apiError = (data: Record<string, unknown>, status = 409) => ({ response: { status, data } });
+
+describe("isHoldExpiredError", () => {
+  it("recognises the 409 the hold endpoints throw", () => {
+    expect(isHoldExpiredError(apiError({ code: HOLD_EXPIRED_CODE, message: "…expired…" }))).toBe(true);
+  });
+
+  it("does NOT treat sold-out as an expired hold", () => {
+    // The whole point of splitting the error out: sold-out has no retry that
+    // can work, an expired hold usually does. Offering the wrong one is the
+    // regression this guards.
+    expect(isHoldExpiredError(apiError({ message: "This ticket is sold out." }, 400))).toBe(false);
+  });
+
+  it("does not fire on a bare 409 with no code", () => {
+    // A 409 is a generic conflict any future endpoint could answer with;
+    // switching on the status alone would offer a retry that cannot help.
+    expect(isHoldExpiredError(apiError({ message: "Conflict" }))).toBe(false);
+  });
+
+  it("is safe on the shapes an unexpected failure actually arrives as", () => {
+    expect(isHoldExpiredError(undefined)).toBe(false);
+    expect(isHoldExpiredError(null)).toBe(false);
+    expect(isHoldExpiredError(new Error("Network Error"))).toBe(false);
+    expect(isHoldExpiredError({})).toBe(false);
+  });
+});
+
+describe("holdExpiredMessage", () => {
+  it("prefers the API's own localised words", () => {
+    const message = "Your ticket reservation expired before payment finished.";
+    expect(holdExpiredMessage(apiError({ code: HOLD_EXPIRED_CODE, message }), "fallback")).toBe(message);
+  });
+
+  it("falls back only when the response carried nothing", () => {
+    expect(holdExpiredMessage(apiError({ code: HOLD_EXPIRED_CODE }), "fallback")).toBe("fallback");
+    expect(holdExpiredMessage(new Error("boom"), "fallback")).toBe("fallback");
+  });
+});
+
+describe("holdMsRemaining", () => {
+  const now = Date.parse("2026-08-09T12:00:00.000Z");
+
+  it("measures the window from now", () => {
+    expect(holdMsRemaining("2026-08-09T12:10:00.000Z", now)).toBe(600_000);
+  });
+
+  it("returns null — NOT zero — when no hold was taken", () => {
+    // `null` is "there is no reservation" (holds switched off for the profile,
+    // a digital-only cart, an already-settled free order); `0` is "a real one
+    // ran out". A surface that conflated them would draw an expired countdown
+    // on every order for every profile with the feature off.
+    expect(holdMsRemaining(null, now)).toBeNull();
+    expect(holdMsRemaining(undefined, now)).toBeNull();
+    expect(holdMsRemaining("", now)).toBeNull();
+  });
+
+  it("returns null for an unparseable instant rather than a bogus countdown", () => {
+    expect(holdMsRemaining("not-a-date", now)).toBeNull();
+  });
+
+  it("clamps a past instant to zero instead of counting up", () => {
+    expect(holdMsRemaining("2026-08-09T11:59:00.000Z", now)).toBe(0);
+  });
+});
+
+describe("formatHoldRemaining", () => {
+  it("renders m:ss", () => {
+    expect(formatHoldRemaining(600_000)).toBe("10:00");
+    expect(formatHoldRemaining(65_000)).toBe("1:05");
+    expect(formatHoldRemaining(9_000)).toBe("0:09");
+  });
+
+  it("rounds UP, so the clock only reads 0:00 when it is genuinely over", () => {
+    // Rounding down put "0:00" on screen for the last whole second of a hold
+    // that was still perfectly valid — a small lie the buyer acts on.
+    expect(formatHoldRemaining(1)).toBe("0:01");
+    expect(formatHoldRemaining(999)).toBe("0:01");
+    expect(formatHoldRemaining(0)).toBe("0:00");
+  });
+
+  it("grows to h:mm:ss for a long window", () => {
+    expect(formatHoldRemaining(3_600_000)).toBe("1:00:00");
+    expect(formatHoldRemaining(3_725_000)).toBe("1:02:05");
+  });
+
+  it("never renders a negative clock", () => {
+    expect(formatHoldRemaining(-5_000)).toBe("0:00");
+  });
+});

package/src/ui/headless/checkout/inventoryHold.ts

@@ -0,0 +1,83 @@
+/**
+ * The inventory hold, as a buyer experiences it.
+ *
+ * The server reserves stock while a buyer is on the card form and reports when
+ * that reservation lapses (`holdExpiresAt`, ISO-8601, on every checkout-create
+ * and every `start-payment` response). When it lapses before the payment lands,
+ * `start-payment` answers **409 `INVENTORY_HOLD_EXPIRED`** — deliberately NOT
+ * the sold-out error, because "your reservation ran out" and "there are none
+ * left" lead the buyer to different next actions and only the first one has a
+ * retry that works.
+ *
+ * None of that was rendered anywhere. This module is the shared, provider-free
+ * half of rendering it, so both stacks (the client PWA and Forge's own styled
+ * drop-ins) count the same clock and read the same error.
+ *
+ * Everything here is pure — no React, no provider tree — so it is unit-testable
+ * on its own, the same reason `bundleCoupon.ts` sits beside it.
+ */
+
+/** The machine-readable code the API stamps on an expired-hold refusal. */
+export const HOLD_EXPIRED_CODE = "INVENTORY_HOLD_EXPIRED";
+
+type MaybeApiError = {
+  response?: { status?: number; data?: { code?: string; message?: string } };
+};
+
+/**
+ * Is this failure "your reservation lapsed" rather than anything else?
+ *
+ * Switches on `code`, never on prose and never on the bare 409 — a 409 alone is
+ * a generic conflict a future endpoint could reuse, and treating one as an
+ * expired hold would offer a retry that cannot help.
+ */
+export function isHoldExpiredError(error: unknown): boolean {
+  return (error as MaybeApiError)?.response?.data?.code === HOLD_EXPIRED_CODE;
+}
+
+/**
+ * The API's own words for a lapsed hold, already localised server-side
+ * (`errors.order.hold_expired` / `errors.event.hold_expired`).
+ *
+ * The fallback is only reached if the response carried no message at all; it is
+ * never used to *replace* the server's message, which is the one that names the
+ * right noun ("basket" vs "tickets").
+ */
+export function holdExpiredMessage(error: unknown, fallback: string): string {
+  return (error as MaybeApiError)?.response?.data?.message || fallback;
+}
+
+/**
+ * Milliseconds until the hold lapses, or `null` when there is no hold.
+ *
+ * `null` and `0` are different facts and the UI must not conflate them:
+ * `holdExpiresAt` is absent for a free/already-settled order and for every
+ * profile with the holds switch off, and inventing a countdown there would
+ * promise a reservation nobody took. Zero means a real hold that has run out.
+ *
+ * Clamped at zero so a stale or clock-skewed instant reads as lapsed rather
+ * than as a negative timer.
+ */
+export function holdMsRemaining(holdExpiresAt: string | null | undefined, now: number): number | null {
+  if (!holdExpiresAt) return null;
+  const ms = Date.parse(holdExpiresAt);
+  if (Number.isNaN(ms)) return null;
+  return Math.max(0, ms - now);
+}
+
+/**
+ * `m:ss` for the countdown, and `h:mm:ss` above an hour.
+ *
+ * Rounds UP, so a hold with 1ms left reads "0:01" and the timer only shows
+ * "0:00" at the instant it is genuinely over — a countdown that sits on zero
+ * for a whole second while payment is still accepted is a small lie the buyer
+ * acts on.
+ */
+export function formatHoldRemaining(msRemaining: number): string {
+  const total = Math.ceil(Math.max(0, msRemaining) / 1000);
+  const seconds = total % 60;
+  const minutes = Math.floor(total / 60) % 60;
+  const hours = Math.floor(total / 3600);
+  const mm = hours > 0 ? String(minutes).padStart(2, "0") : String(minutes);
+  return `${hours > 0 ? `${hours}:` : ""}${mm}:${String(seconds).padStart(2, "0")}`;
+}

package/src/ui/headless/checkout/useCheckout.ts

@@ -18,6 +18,8 @@ import {
   type ApplyCheckoutCouponResult,
 } from "../../../data/queries/useCheckouts";
 import { bundleCouponSummary, bundleReturnUrl } from "./bundleCoupon";
+import { holdExpiredMessage, isHoldExpiredError } from "./inventoryHold";
+import { useInventoryHold } from "./useInventoryHold";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
@@ -289,6 +291,58 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
 
   const orderId = created?.orderId ?? null;
 
+  // ── Inventory hold ──────────────────────────────────────────────────────────
+  /**
+   * The reservation clock the buyer is counting down.
+   *
+   * `start-payment` RESTARTS the hold and reports the new instant, so its figure
+   * supersedes the one `createOrder` returned — that one was measured before the
+   * buyer had even seen a payment field. The create-time value bridges the
+   * moment in between, which for a slow `start-payment` is the whole of the
+   * buyer's first impression of the page.
+   *
+   * A bundle has no create-time figure at all (`POST /public/checkouts` takes
+   * the holds but does not report a window), so it is start-payment or nothing —
+   * which is fine, because a bundle always starts payment immediately.
+   *
+   * `undefined` on an older API and `null` whenever no hold was taken; both mean
+   * "render nothing", which is exactly today's behaviour.
+   */
+  const holdExpiresAt = flow.result?.holdExpiresAt ?? created?.holdExpiresAt ?? null;
+  const hold = useInventoryHold(holdExpiresAt);
+
+  /**
+   * The reservation ran out before the payment landed (409
+   * `INVENTORY_HOLD_EXPIRED`), which is NOT sold-out — the items may well still
+   * be there, and re-running `start-payment` re-acquires the very same units
+   * when they are. Told apart from every other start failure so the buyer is
+   * offered the retry that actually works instead of a dead end.
+   */
+  const isHoldExpired = isHoldExpiredError(flow.error);
+  const holdExpiredError = isHoldExpired
+    ? holdExpiredMessage(flow.error, "Your basket reservation expired before payment finished. Please try again.")
+    : "";
+
+  /**
+   * Take the reservation again on the SAME order or bundle.
+   *
+   * The cheapest recovery there is: nothing about the cart has changed, so if
+   * the units are still free the buyer gets a fresh window and the card form
+   * they were already looking at. If they are genuinely gone, another 409 says
+   * so — and that is the point at which "change your selection" is the honest
+   * next step, not before.
+   */
+  const retryHold = useCallback(async () => {
+    if (!created?.orderId && !checkoutId) return;
+    try {
+      await flow.start();
+    } catch {
+      // The refusal is already on `flow.error`; a rethrow here would only turn a
+      // handled state into an unhandled rejection.
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [created?.orderId, checkoutId]);
+
   // A coupon re-issues the payment intent, so its update supersedes the initial
   // start-payment result. Otherwise use the started payment once both the order
   // and start-payment have resolved.
@@ -589,6 +643,24 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
     startError,
+    // ── Inventory hold ─────────────────────────────────────────────────────────
+    /**
+     * The live reservation: `isHeld` + `label` while it runs, `hasLapsed` once
+     * the clock hits zero. Every field is null/false when no hold was taken, so
+     * a surface guarding on `isHeld || hasLapsed` is unchanged for the profiles
+     * that have holds switched off.
+     */
+    hold,
+    /**
+     * The server said the reservation expired (409 `INVENTORY_HOLD_EXPIRED`) —
+     * its own words, already localised. Empty for every other failure, so this
+     * can never be mistaken for sold-out.
+     */
+    holdExpiredError,
+    isHoldExpired,
+    /** Re-take the reservation on the same order/bundle. See `retryHold`. */
+    retryHold,
+    isRetryingHold: flow.isStarting,
     provider,
     isPaystack: provider === PaymentProviderName.Paystack,
     paymentSecret: effectivePayment?.paymentSecret,

package/src/ui/headless/checkout/useInventoryHold.ts

@@ -0,0 +1,104 @@
+import { useEffect, useRef, useState } from "react";
+import { formatHoldRemaining, holdMsRemaining } from "./inventoryHold";
+
+export interface InventoryHoldState {
+  /**
+   * True only while a real reservation is running. False both when there is no
+   * hold at all and once one has run out — the two are told apart by
+   * `hasLapsed`, and no surface should draw a timer off this alone.
+   */
+  isHeld: boolean;
+  /** True when a hold existed and its clock reached zero on this device. */
+  hasLapsed: boolean;
+  /** The instant the API reported, unchanged; `null` when no hold was taken. */
+  expiresAt: string | null;
+  /** Milliseconds left, or `null` when there is no hold. */
+  msRemaining: number | null;
+  /** Whole seconds left, or `null` when there is no hold. */
+  secondsRemaining: number | null;
+  /** `m:ss` (or `h:mm:ss`) for display; `null` when there is nothing to count. */
+  label: string | null;
+  /** Under two minutes — the point at which a surface should stop being subtle. */
+  isUrgent: boolean;
+}
+
+export interface UseInventoryHoldOptions {
+  /**
+   * Fired once, when a running clock reaches zero. For telling a flow to stop
+   * describing the reservation as live; NOT for tearing the payment form down.
+   */
+  onLapse?: () => void;
+  /** Tick interval, ms. Only for tests — a second is what a countdown means. */
+  intervalMs?: number;
+}
+
+/**
+ * Count down an inventory hold.
+ *
+ * ## What it does at zero, and why
+ *
+ * It stops, and it flips `hasLapsed`. A timer that reaches 0:00 and then keeps
+ * sitting there is worse than no timer: it has told the buyer something has
+ * happened and then refuses to say what. So the honest end state is a *changed
+ * statement* — "your reservation has ended" — which the calling surface renders
+ * in place of the clock, with the same recovery action a 409 gets.
+ *
+ * It deliberately does **not** hide or disable the payment form. This clock is
+ * the buyer's device clock against an instant the server chose; it can be
+ * skewed, and the server may still accept the payment (`start-payment`
+ * re-acquires the same units when they are still free). Refusing a charge the
+ * server would have taken loses a real sale to defend a display detail. The
+ * authority stays where it belongs — the 409, when it comes.
+ *
+ * ## Degrading to today's behaviour
+ *
+ * Holds are behind a per-profile switch that most profiles have off, and a free
+ * or already-settled order never carries one either. In all of those cases
+ * `holdExpiresAt` is `null`/absent, every field here is null/false, and a
+ * surface that guards on `isHeld || hasLapsed` renders exactly what it renders
+ * today.
+ */
+export function useInventoryHold(
+  holdExpiresAt: string | null | undefined,
+  opts: UseInventoryHoldOptions = {},
+): InventoryHoldState {
+  const { onLapse, intervalMs = 1000 } = opts;
+  const [msRemaining, setMsRemaining] = useState<number | null>(() => holdMsRemaining(holdExpiresAt, Date.now()));
+  // Keeps the callback out of the effect's dependencies, so an inline arrow
+  // from the caller does not restart the interval on every render.
+  const onLapseRef = useRef(onLapse);
+  onLapseRef.current = onLapse;
+
+  useEffect(() => {
+    const initial = holdMsRemaining(holdExpiresAt, Date.now());
+    setMsRemaining(initial);
+    // No hold, or one that was already over when we first saw it (a resumed tab,
+    // a skewed clock): nothing to tick. The already-over case still reports
+    // `hasLapsed` below — it just never animated down to it.
+    if (initial === null || initial <= 0) return;
+
+    const id = setInterval(() => {
+      const next = holdMsRemaining(holdExpiresAt, Date.now());
+      setMsRemaining(next);
+      if (next !== null && next <= 0) {
+        clearInterval(id);
+        onLapseRef.current?.();
+      }
+    }, intervalMs);
+    return () => clearInterval(id);
+  }, [holdExpiresAt, intervalMs]);
+
+  const hasHold = msRemaining !== null;
+  const hasLapsed = hasHold && msRemaining <= 0;
+  const isHeld = hasHold && msRemaining > 0;
+
+  return {
+    isHeld,
+    hasLapsed,
+    expiresAt: holdExpiresAt ?? null,
+    msRemaining,
+    secondsRemaining: hasHold ? Math.ceil(msRemaining / 1000) : null,
+    label: isHeld ? formatHoldRemaining(msRemaining) : null,
+    isUrgent: isHeld && msRemaining <= 120_000,
+  };
+}