@encorekit/web-sdk 2.0.7 → 2.1.1

package/types/core/giftVariant.d.ts

@@ -0,0 +1,67 @@
+/**
+ * WHICH SERVED VARIANT GETS WHICH GIFT SURFACE.
+ *
+ * The gift flows are CUSTOM SURFACES FOR ONE PUBLISHER, not a platform change. Every
+ * other `rewardUsers` publisher keeps the paged `OfferCarousel` exactly as before, so
+ * the selector cannot be the use case — it has to be the variant the backend serves,
+ * which is the same per-app machinery `streaksCarousel` already rides
+ * (`GET /publisher/sdk/v1/config` → `ui.variantName`).
+ *
+ * THREE NAMES, EACH ITS OWN SURFACE. `giftReveal` is the name in the approved Backend
+ * Change Report (the box that opens onto a short radio group). `giftList` and
+ * `giftUnwrap` are the two later designs (a selectable list under a hero image, and a
+ * closed box that unwraps onto a "your gift is ready" screen). The names are fixed:
+ * they are what the `variants` rows will be called and what the config endpoint will
+ * serve as `selectedVariant.name`. They sit beside the shipped variants
+ * (bundleFraming, control, customHeadlineControl, featuredOfferCarousel,
+ * fullscreenVerticalLayout, fullScreenWithBundleTags, iapFirstThankYouOffers,
+ * offerwallWithIAPAndOffers, reasonBasedRecovery, streaksCarousel, thankyouOffers,
+ * tillFinancial, verticalListAsyncAdvertiser) rather than replacing any of them.
+ *
+ * A NAME CAN RESOLVE AHEAD OF ITS SURFACE. The resolver says which surface a variant
+ * ASKS for; `Encore` decides whether that surface exists in this build. A kind with no
+ * surface yet renders the carousel, so resolving a name here is never on its own a
+ * switch of anyone's sheet.
+ *
+ * 🔴 SAFE TO SHIP AHEAD OF THE ROWS, and that is the fail-safe direction working, not
+ * a gap. Until a variant with one of these names exists AND is activated for an app,
+ * nothing serves that name: `rewardSurfaceKind` returns null for every publisher,
+ * including PayRange, and every one of them keeps the existing `OfferCarousel`. The
+ * day a row is activated is the day its surface turns on, for exactly the apps it is
+ * activated for, with no SDK release in between.
+ *
+ * WHY AN ALLOWLIST RATHER THAN A FLAG ON THE VARIANT: nothing in the served payload
+ * says "this variant wants a bespoke web surface", and adding such a field is a
+ * backend contract change. Matching on the name keeps the decision in one place in
+ * this SDK, visible in review, and costs one string per surface.
+ */
+/** The bespoke reward surfaces a served variant can ask for. */
+export type RewardSurfaceKind = 'giftReveal' | 'giftList' | 'giftUnwrap';
+/**
+ * Exact served variant name → the surface it asks for. The ONLY way into any gift
+ * surface: a name missing from this table is the carousel.
+ *
+ * Frozen as well as typed readonly, because this is a routing allowlist and a
+ * `Readonly` type stops a mutation in TypeScript only.
+ */
+export declare const REWARD_VARIANT_TABLE: Readonly<Record<string, RewardSurfaceKind>>;
+/**
+ * Which bespoke surface the served variant asks for, or null for the carousel.
+ *
+ * ABSENT, NULL, UNKNOWN AND EMPTY ALL MEAN NULL. A name only arrives in a backend
+ * response for the app (the eager `/config` block, or the lazy `?useCase=` fetch Encore
+ * awaits when the eager one is slower than `DISPLAY_CONFIG_WAIT_MS`). When neither
+ * resolves one, there is no name, and the publisher must get the surface they already
+ * had rather than one they never opted into — so the only way to reach a gift surface
+ * is an explicit, positive, EXACT match: no trimming, no case folding, no prefix.
+ */
+export declare function rewardSurfaceKind(variantName: string | null | undefined, 
+/**
+ * The table to match against. Injectable so the matching rule can be exercised
+ * independently of what the shipped table holds: a test that only ever used the real
+ * one would stop distinguishing exact matching from prefix, trimmed or
+ * case-insensitive matching the moment the shipped table changed shape. Production
+ * callers pass one argument.
+ */
+table?: Readonly<Record<string, RewardSurfaceKind>>): RewardSurfaceKind | null;
+//# sourceMappingURL=giftVariant.d.ts.map

package/types/core/giftVariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"giftVariant.d.ts","sourceRoot":"","sources":["../../src/core/giftVariant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAI3E,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;AACtC;;;;;;GAMG;AACH,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAwB,GACxE,iBAAiB,GAAG,IAAI,CAO1B"}

package/types/core/version.d.ts

@@ -1,3 +1,3 @@
 /** SDK version — single source of truth (also kept in sync with package.json via scripts/update-version.sh) */
-export declare const SDK_VERSION = "2.0.7";
+export declare const SDK_VERSION = "2.1.1";
 //# sourceMappingURL=version.d.ts.map

package/types/types.d.ts

@@ -145,13 +145,32 @@ export interface AppearanceConfig {
     headline?: TextSlot;
     /** The line under the heading. Same three forms. */
     subheadline?: TextSlot;
-    /** The "Claim gift" CTA. The SDK keeps the claim action — see the interface docs. */
+    /**
+     * The claim CTA. The SDK keeps the claim action — see the interface docs.
+     *
+     * ON THE GIFT VARIANT its shipped copy NAMES the selected gift ("Claim 1 month of
+     * Apple Music") and re-words as the selection changes. Every other reward publisher
+     * is on the carousel, where it stays the generic "Claim gift" — this is scoped to
+     * the served variant, like the surface itself. A style config's own `text`, and any
+     * element or renderer you supply, still win outright on both: the SDK never rewrites
+     * copy a publisher wrote.
+     */
     claimButton?: ButtonSlot;
     /** The "No thanks" decline button. The SDK keeps the decline action. */
     declineButton?: ButtonSlot;
-    /** The page indicator's inactive dots. */
+    /**
+     * Colours for the reward carousel's page indicator.
+     *
+     * LIVE, and not deprecated. They were briefly documented as inert while the gift
+     * flow replaced the reward carousel for every publisher; that flow is scoped to one
+     * served variant now, so the carousel — and its indicator — is what almost every
+     * reward publisher still renders.
+     *
+     * They have no effect on the GIFT surface alone, which puts every gift on screen at
+     * once and pages nothing, so it has no indicator to colour.
+     */
     dotColor?: string;
-    /** The page indicator's active dot. */
+    /** Active-page colour for the same indicator. See {@link AppearanceConfig.dotColor}. */
     dotActiveColor?: string;
 }
 /**
@@ -399,6 +418,15 @@ export interface EncoreConfig {
      * see docs/architecture/platform-divergence/web.md.
      */
     unlockMode?: 'strict' | 'optimistic';
+    /**
+     * The user's id when it is already known at load time (a login, or the `userId` on
+     * a hosted offer link). Applied BEFORE the SDK's first request, so the `/config`
+     * that assigns experiment arms runs as this user rather than as an anonymous id it
+     * then abandons. An anonymous id this browser stored earlier is aliased to it,
+     * exactly as `identify()` does. Trimmed; blank is ignored. `identify()` still works
+     * for a login that happens later.
+     */
+    userId?: string;
 }
 /** Result of `show()` / `present()`. */
 export type ShowResult = 

package/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/types/ui/GiftHero.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Gift hero — the box that opens.
+ *
+ * The lid and bow fly up and off while the chosen gifts rise out of the box behind
+ * them, and a confetti burst fires from the opening. It is the one moment in the
+ * reward sheet that is pure delight rather than information, and it is the reason the
+ * flow reads as a gift instead of an ad unit.
+ *
+ * NOT a renderer, the same way `RewardCard` is not: web has no SDUI engine, so every
+ * dimension below is read off the design by hand and tracked here.
+ *
+ *   box        270×236 stage; back 138×60 @ (66,112), front 150×90 @ (60,134)
+ *   lid        170×26 @ (50,118), flies to (+6,-170) rotate -14deg over .55s
+ *   bow        100×36 @ (85,98), rides the lid
+ *   tiles      64×64 (centre tile 78×78), rise to (-74,-88) / (-7,-126) / (72,-88)
+ *   confetti   bursts from the mouth of the box
+ *
+ * ALL MOTION IS CSS. The SDK ships zero runtime dependencies and this is a decorative
+ * flourish on a sheet that must never be the reason a publisher's page janks — so the
+ * whole animation is four keyframes and a class toggle, and the only JavaScript is the
+ * toggle itself. The single canvas is `RewardConfetti`, which the reward sheet already
+ * ships; this hero reuses it with a burst origin rather than introducing a second one.
+ *
+ * `prefers-reduced-motion` is handled in the stylesheet, not here: the reduced-motion
+ * block places the lid, bow and tiles directly in their final state, so the hero still
+ * shows an OPEN box with the gifts out of it rather than a closed box that never
+ * opens. The confetti skips itself — see `RewardConfetti.shouldSkip`.
+ */
+import type { OfferModel as Offer } from '../api/models';
+/**
+ * How many gifts the box can show at once.
+ *
+ * Three is the design, and it is also the honest ceiling: the tiles are hand-placed at
+ * three fixed positions because a generic fan-out would need layout maths for a shape
+ * that is never asked for. A fourth offer does not go in the box — it goes in the
+ * "other gifts" sheet, which is exactly what that sheet is for.
+ */
+export declare const HERO_TILE_LIMIT = 3;
+export declare class GiftHero {
+    #private;
+    /**
+     * Build the closed box with `offers` inside it. Renders at most
+     * {@link HERO_TILE_LIMIT} tiles; the rest of the offers live in the sheet.
+     *
+     * `aria-hidden` throughout: everything the hero depicts is stated in text directly
+     * below it, so announcing the tiles as well would make a screen reader read the
+     * whole gift list twice before reaching the radio group that actually selects one.
+     */
+    render(offers: readonly Offer[]): HTMLElement;
+    /**
+     * Re-point the tiles at a new set of gifts, without re-opening the box.
+     *
+     * Promotion swaps a gift out of the rows and one in from the sheet, and the hero
+     * depicts exactly those rows — so leaving it alone would show a brand that is no
+     * longer selectable while hiding the one the user just chose.
+     *
+     * Only the tile's CONTENTS change. The tile elements keep their positions, their
+     * finished rise transforms and the running bob, so this is a quiet swap rather than
+     * a second unboxing: the box has already opened and should not appear to re-open.
+     */
+    updateTiles(offers: readonly Offer[]): void;
+    /**
+     * Open the box.
+     *
+     * Deferred one frame because the sheet is still detached when the caller composes it,
+     * and an animation started on a node with no layout box begins mid-flight — the lid
+     * would already be gone by the time the sheet is visible.
+     *
+     * Guarded end to end: this is decoration on someone else's page, and a hero that
+     * throws would take the whole reward presentation down with it.
+     */
+    play(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=GiftHero.d.ts.map

package/types/ui/GiftHero.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GiftHero.d.ts","sourceRoot":"","sources":["../../src/ui/GiftHero.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,eAAe,CAAC;AA6BzD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAwBjC,qBAAa,QAAQ;;IAanB;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,WAAW;IAmC7C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI;IAgF3C;;;;;;;;;OASG;IACH,IAAI,IAAI,IAAI;IA4GZ,OAAO,IAAI,IAAI;CAahB"}

package/types/ui/GiftList.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Gift list — the `giftList` reward surface (Figma "hypothesis 3", node 19796:48052).
+ *
+ * Top to bottom, inside the reward chrome: "{app icon} Presents" above the headline
+ * ({@link GiftList.renderHero}), then this surface — the SELECTED offer's artwork, up
+ * to three selectable rows with the selected one expanded to show its description, and
+ * "Show more gifts" when there are more — then the action block Encore composes: one
+ * CTA that names the selection, and the shared terms line under it.
+ *
+ * 🔴 SCOPED TO ONE VARIANT. Reached only when the backend serves `giftList` for a
+ * `rewardUsers` presentation (see `core/giftVariant.ts`); every other publisher keeps
+ * the carousel, and `giftReveal` keeps its box.
+ *
+ * ## What it shares with GiftReveal, and what it does not
+ *
+ * The SELECTION MODEL is the same one, deliberately: `#selectedIndex` indexes the FULL
+ * offer array, and a gift picked from the sheet is PROMOTED into the rows rather than
+ * tracked beside them, so the screen and the CTA can never disagree about what will be
+ * claimed. The sheet itself is literally the same code (`GiftSheet`). The rows, the
+ * artwork and the motion are this design's own, and share no element with the box.
+ *
+ * ## What the design shows that this does not build
+ *
+ * - The "Most claimed" pill on one row. There is no popularity, claim-count or
+ *   ranking field anywhere in the offer contract (`api/models.ts`), so which row would
+ *   carry it cannot be known. It waits on a real field.
+ * - The three-card fan behind the headline. The design draws Disney's multi-title art
+ *   as three posters; an offer carries ONE `imageUrl`, so one image is shown, sized as
+ *   the fan's centre card. Duplicating it into side cards would picture three titles
+ *   the offer never named.
+ * - A grey ring on unselected rows. SPEC.md describes one; the frame render has none
+ *   (sampled: white where the ring would be), and the frame is the source of truth.
+ *
+ * ## Events
+ *
+ * `offerView` once per offer the impression gate judges shown (a row, a promoted row, a
+ * sheet card while the sheet is open), `offerSelect` on every selection change including the
+ * initial auto-selection from inside `render()`, `offerClaim` only from a user gesture
+ * reaching {@link GiftList.claimSelected}. Nothing else — never `scroll` or `complete`.
+ * Every payload's `index` indexes the array Encore passed in.
+ */
+import type { OfferModel as Offer } from '../api/models';
+import type { RewardSurface, RewardSurfaceEventMap } from './rewardSurface';
+import { ImpressionGate } from './impressionGate';
+/** How many gifts are shown as rows. The rest go behind "Show more gifts". */
+export declare const GIFT_LIST_ROW_LIMIT = 3;
+/**
+ * The artwork cross-fade on a selection change, matching the CSS animation duration.
+ * The outgoing image is removed on a timer of this length rather than on
+ * `animationend`, which never fires when the animation does not run (reduced motion,
+ * a hidden tab, an environment with no layout engine) and would strand it on screen.
+ */
+export declare const ART_FADE_MS = 200;
+export interface GiftListOptions {
+    /**
+     * Whether claiming is switched on. `false` keeps the sheet's CTA inert, matching the
+     * main CTA — the gate is the SDK's, so every control that can start a claim honours it.
+     */
+    claimEnabled?: boolean;
+    /** The host app's icon (`/config` `ui.values.media.appstoreIcon`), for "Presents". */
+    hostIconUrl?: string;
+    /** The host app's name, the icon's accessible text. */
+    hostName?: string;
+    /**
+     * The presentation's impression gate (see `impressionGate.ts`): rows and sheet cards
+     * report `offerView` only once it judges them shown. Without one the surface owns an
+     * unarmed gate, which never fires.
+     */
+    impressions?: ImpressionGate;
+}
+export declare class GiftList implements RewardSurface {
+    #private;
+    constructor(offers: readonly Offer[], options?: GiftListOptions);
+    on<E extends keyof RewardSurfaceEventMap>(event: E, handler: (payload: RewardSurfaceEventMap[E]) => void): () => void;
+    getTotalOffers(): number;
+    getCurrentIndex(): number;
+    getSelectedOffer(): Offer | undefined;
+    /** True when there is anything left to put behind "Show more gifts". */
+    hasMoreGifts(): boolean;
+    /**
+     * "{host app icon} Presents", the row above the headline.
+     *
+     * Separate from {@link render} because it belongs ABOVE the chrome's headline and the
+     * rows belong below it — see `RewardLayoutOptions.hero`. Returns `undefined` when the
+     * host has no usable icon: the icon is the subject of "Presents", and the word alone
+     * says nothing. The icon is the HOST's, from config; it is never rotated (the design
+     * tilts its placeholder 9°, which would be restyling a publisher's brand mark).
+     */
+    renderHero(): HTMLElement | undefined;
+    render(): HTMLElement;
+    /**
+     * Select the offer at `index` — an index into the full offer array.
+     *
+     * Out-of-range indices are IGNORED rather than clamped: silently claiming a
+     * neighbouring advertiser's offer would hide a caller's bug behind a real transaction.
+     */
+    selectOffer(index: number): void;
+    /** Move to the next offer, wrapping. Present for API parity with the carousel. */
+    next(): void;
+    /**
+     * Claim the SELECTED offer — the single claim path, whichever control started it.
+     * Honours the host's claim switch here as well as on the buttons, so a programmatic
+     * call cannot claim what a disabled control could not.
+     */
+    claimSelected(): void;
+    openSheet(opener?: HTMLElement): void;
+    closeSheet(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=GiftList.d.ts.map

package/types/ui/GiftList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GiftList.d.ts","sourceRoot":"","sources":["../../src/ui/GiftList.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,eAAe,CAAC;AASzD,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAEnE,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,MAAM,CAAC;AAkB/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AASD,qBAAa,QAAS,YAAW,aAAa;;gBAiChC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,OAAO,GAAE,eAAoB;IASnE,EAAE,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACtC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,GACnD,MAAM,IAAI;IAIb,cAAc,IAAI,MAAM;IAIxB,eAAe,IAAI,MAAM;IAIzB,gBAAgB,IAAI,KAAK,GAAG,SAAS;IAIrC,wEAAwE;IACxE,YAAY,IAAI,OAAO;IAIvB;;;;;;;;OAQG;IACH,UAAU,IAAI,WAAW,GAAG,SAAS;IA6BrC,MAAM,IAAI,WAAW;IAyKrB;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAehC,kFAAkF;IAClF,IAAI,IAAI,IAAI;IAkDZ;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAsJrB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI;IAKrC,UAAU,IAAI,IAAI;IAIlB,OAAO,IAAI,IAAI;CAehB"}

package/types/ui/GiftReveal.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Gift reveal — the `rewardUsers` selection surface.
+ *
+ * Replaces the paged card carousel for the reward composition: the box opens, the
+ * gifts come out of it, and the user picks one from a short radio group with a CTA
+ * that names what they picked. Everything that did not fit in the box lives behind
+ * "Other gifts".
+ *
+ * 🔴 SCOPED TO `rewardUsers`. `reduceChurn` keeps `OfferCarousel` untouched — it is a
+ * different surface with its own per-card claim funnel and its own NCL experiment
+ * wiring, and nothing here is reachable from it.
+ *
+ * ## Why this is not a mode on OfferCarousel
+ *
+ * The same reason `RewardCard` is not a flag on `OfferCard`. A carousel is one card at
+ * a time with paging, scroll settling, impression dedup on rest, an
+ * IntersectionObserver for its vertical mode and a listbox for its horizontal one.
+ * This is a static list of three rows, all on screen, all impressed at once, with no
+ * scrolling of any kind. They share no element and no state machine, and expressing
+ * both in one class would be a component that renders two unrelated surfaces with the
+ * churn funnel one boolean away from the reward one.
+ *
+ * ## Selection has exactly one source
+ *
+ * `#selectedIndex`, an index into the FULL offer array — including offers currently
+ * behind the sheet. Picking a gift from the sheet PROMOTES it into the visible rows
+ * rather than tracking a second selection beside them, because two selections is
+ * precisely the shape that shipped a CTA claiming a different offer from the one the
+ * screen showed (the artifact this tracks has that bug: its sheet keeps `sheetSel`
+ * alongside the row selection, and the two disagree on screen).
+ *
+ * ## Events
+ *
+ * Emits the subset of `OfferCarousel`'s event map the reward path consumes —
+ * `offerClaim`, `offerSelect`, `offerView` — with identical payloads, so the claim
+ * funnel, the transaction creation and the `use_case`-stamped analytics in `Encore.ts`
+ * are reached through exactly one path whichever surface rendered. It never emits
+ * `scroll` (nothing scrolls) or `complete` (there is no last card to decline).
+ *
+ * ⚠️ IMPRESSION GRAIN DIFFERS FROM THE CAROUSEL, and that is the honest reading. The
+ * carousel emits one `offerView` per card it settles on; this surface shows every
+ * visible row at once, so each row reports once the impression gate judges it shown
+ * (sheet visible, tab visible, half on screen). Sheet cards report the same way, and
+ * only while the sheet is open.
+ */
+import type { OfferModel as Offer } from '../api/models';
+import { SHEET_CLOSE_MS } from './GiftSheet';
+import type { RewardSurface, RewardSurfaceEventMap } from './rewardSurface';
+import { ImpressionGate } from './impressionGate';
+/** How many gifts are shown as rows. The rest go behind "Other gifts". */
+export declare const GIFT_ROW_LIMIT = 3;
+/** Re-exported: the sheet moved to `GiftSheet`, and this is where its tests import it from. */
+export { SHEET_CLOSE_MS };
+export interface GiftRevealOptions {
+    /**
+     * Whether claiming is switched on. `false` disables the sheet's own CTA, matching
+     * what `RewardActions` does to the main one — the gate is the SDK's, so every
+     * control that can start a claim has to honour it, not just the visible one.
+     */
+    claimEnabled?: boolean;
+    /**
+     * The trust line repeated at the foot of the sheet.
+     *
+     * Passed in by the caller so it is literally the SAME value the main surface's
+     * action block receives — the two are one decision made once, not two defaults that
+     * happen to agree. The fallback is now that same string rather than a second
+     * constant that has to be kept in step with it.
+     *
+     * 🔴 THE FALLBACK CLAIMS NOTHING, AND IT CANNOT BE DERIVED. Every other fine print
+     * in this SDK is chosen per offer from `badgeLabel` — `isKnownFreeTrial` picks
+     * `GIFT_COPY.finePrint`, everything else gets `REWARD_COPY.trustUnknown` — but this
+     * line sits at the foot of a LIST. The sheet holds every gift that did not fit, one
+     * row can be a free trial and the next a paid discount, and the sheet's own CTA is
+     * "Continue" rather than a claim, so there is no single offer whose badge could
+     * decide the sentence. The badge route is unavailable here for that reason, not
+     * because the data is missing.
+     *
+     * It used to default to `GIFT_COPY.finePrint` — "FREE trial. You can cancel
+     * anytime." — over exactly that mixed list: the same false claim `ui/offerBadge.ts`
+     * exists to remove, asserted over more offers at once. The default is now the line
+     * that holds whatever the terms turn out to be.
+     */
+    trustText?: string;
+    /**
+     * The presentation's impression gate (see `impressionGate.ts`): rows and sheet cards
+     * report `offerView` only once it judges them shown. Without one the surface owns an
+     * unarmed gate, which never fires.
+     */
+    impressions?: ImpressionGate;
+}
+export declare class GiftReveal implements RewardSurface {
+    #private;
+    constructor(offers: readonly Offer[], options?: GiftRevealOptions);
+    on<E extends keyof RewardSurfaceEventMap>(event: E, handler: (payload: RewardSurfaceEventMap[E]) => void): () => void;
+    getTotalOffers(): number;
+    getCurrentIndex(): number;
+    getSelectedOffer(): Offer | undefined;
+    /** True when there is anything left to put behind "Other gifts". */
+    hasMoreGifts(): boolean;
+    /**
+     * The opening box, as its own element.
+     *
+     * Separate from {@link render} because the hero belongs ABOVE the sheet's headline
+     * and the rows belong below it — see `RewardLayoutOptions.hero`. Call this first;
+     * `render()` is what starts the animation, once both halves exist.
+     */
+    renderHero(): HTMLElement;
+    render(): HTMLElement;
+    /**
+     * Select the offer at `index` — an index into the full offer array.
+     *
+     * Out-of-range indices are IGNORED rather than clamped: a caller asking for an offer
+     * that does not exist has a bug, and silently claiming a neighbouring advertiser's
+     * offer instead would hide it behind a real transaction.
+     */
+    selectOffer(index: number): void;
+    /** Move to the next offer, wrapping. Present for API parity with the carousel. */
+    next(): void;
+    /**
+     * Claim the SELECTED offer — the single claim path, whichever control started it.
+     *
+     * Honours the host's claim switch here as well as on the buttons, so a programmatic
+     * call cannot claim what a disabled control could not. Otherwise mirrors
+     * `OfferCarousel.claimSelected`, including the warn-and-ignore on an empty
+     * selection: an offers array that arrived empty must not produce a transaction for
+     * `undefined`.
+     */
+    claimSelected(): void;
+    openSheet(opener?: HTMLElement): void;
+    closeSheet(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=GiftReveal.d.ts.map

package/types/ui/GiftReveal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GiftReveal.d.ts","sourceRoot":"","sources":["../../src/ui/GiftReveal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,eAAe,CAAC;AAOzD,OAAO,EAAa,cAAc,EAAiB,MAAM,aAAa,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAEnE,0EAA0E;AAC1E,eAAO,MAAM,cAAc,IAAkB,CAAC;AAE9C,+FAA+F;AAC/F,OAAO,EAAE,cAAc,EAAE,CAAC;AAK1B,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,qBAAa,UAAW,YAAW,aAAa;;gBA2BlC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,OAAO,GAAE,iBAAsB;IASrE,EAAE,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACtC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,GACnD,MAAM,IAAI;IAIb,cAAc,IAAI,MAAM;IAIxB,eAAe,IAAI,MAAM;IAIzB,gBAAgB,IAAI,KAAK,GAAG,SAAS;IAIrC,oEAAoE;IACpE,YAAY,IAAI,OAAO;IAIvB;;;;;;OAMG;IACH,UAAU,IAAI,WAAW;IAIzB,MAAM,IAAI,WAAW;IAuJrB;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAchC,kFAAkF;IAClF,IAAI,IAAI,IAAI;IAmDZ;;;;;;;;OAQG;IACH,aAAa,IAAI,IAAI;IA8CrB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI;IAKrC,UAAU,IAAI,IAAI;IAIlB,OAAO,IAAI,IAAI;CAahB"}

package/types/ui/GiftSheet.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The "other gifts" sheet, shared by the gift surfaces.
+ *
+ * Extracted from `GiftReveal` when `GiftList` needed the same sheet: a scrim, a
+ * bottom sheet holding every gift the surface's rows could not fit, a CTA that names
+ * the pick, and the focus, Escape and Tab containment that make it safe to put over a
+ * claim CTA. Both surfaces render the same DOM through this class, so the sheet's
+ * guarantees are written and tested once.
+ *
+ * WHAT STAYS WITH THE SURFACE. The sheet owns no selection. It asks the surface which
+ * offers it lists (`listed`), registers its cards for impressions while open, and hands the
+ * committed pick back (`onCommit`); the surface promotes, selects and claims. That is
+ * what keeps each surface's "selection has exactly one source" rule intact: the sheet
+ * holds a PICK only until its CTA is pressed, and a pick is not a selection.
+ *
+ * WHAT DIFFERS PER SURFACE is only the line under the sheet's CTA, so it is a builder:
+ * `GiftReveal` repeats its trust line, `GiftList` shows the shared terms line.
+ */
+import type { OfferModel as Offer } from '../api/models';
+import type { ImpressionGate } from './impressionGate';
+import type { GiftCategoryGroup } from './giftCategoryGroups';
+/**
+ * How long the sheet takes to slide away, matching its CSS `transition` duration.
+ * Exported so a test can wait exactly as long as the stylesheet does rather than
+ * guessing, and so the two cannot drift apart silently.
+ */
+export declare const SHEET_CLOSE_MS = 300;
+/**
+ * Guarded `prefers-reduced-motion`. Mirrors `RewardConfetti.shouldSkip` rather than
+ * importing it: this is a question about the sheet, not about confetti, and a host
+ * without `matchMedia` gets the animation, which is the default every other motion in
+ * this SDK takes.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * The advertiser's logo, or a monogram. Mirrors `RewardCard.#createIcon`: a missing
+ * or broken `logoUrl` is the ordinary rendering for an offer without one. The
+ * monogram's letter comes from `giftHost`, the same name the row shows.
+ */
+export declare function buildGiftIcon(offer: Offer, className: string): HTMLElement;
+/**
+ * The tabs for these offers, in `GIFT_CATEGORY_GROUPS` order, or `[]` for no tab strip.
+ *
+ * Every offer has a group: its served category is mapped by `giftCategoryGroup`, and an
+ * absent or unknown one files under Everyday, so nothing is hidden and there is no
+ * "More" tab. Groups with no offers are dropped. The strip is drawn only when at least
+ * two groups each hold two or more offers: below that a tab is a label on one card, and
+ * a shelf with no categories at all (today's backend) must render exactly as it did
+ * before. There is no "All" tab: the design has none, and the first group shown is
+ * selected by default.
+ */
+export declare function sheetCategories(offers: readonly (Offer | undefined)[]): GiftCategoryGroup[];
+export interface GiftSheetOptions {
+    /** The surface's FULL offer array. Every index below indexes it. */
+    offers: readonly Offer[];
+    /** Which offers the sheet lists right now. Read on every list render. */
+    listed: () => readonly number[];
+    /** Whether claiming is switched on. `false` keeps the sheet's CTA inert. */
+    claimEnabled?: boolean;
+    /** The line under the sheet's CTA, or null for none. Built once, at render. */
+    footer: () => HTMLElement | null;
+    /** The sheet's CTA was pressed with `index` picked. The surface selects and claims. */
+    onCommit: (index: number) => void;
+    /** The pick changed: the picked offer, or null once cleared. The footer follows it. */
+    onPick?: (offer: Offer | null) => void;
+    /** The surface's impression gate. Cards are registered only while the sheet is open. */
+    impressions: ImpressionGate;
+    /** The gate judged the card for `index` shown. The surface emits the impression. */
+    onShown: (index: number) => void;
+    /** The surface's listener lifetime; aborting it detaches every sheet listener. */
+    signal: AbortSignal;
+    /** The sheet's heading and group name. Defaults to `GIFT_COPY.sheetTitle` ("Other gifts"). */
+    title?: string;
+    /** The close control's accessible name. Defaults to `GIFT_COPY.closeSheetLabel`. */
+    closeLabel?: string;
+    /**
+     * Fill one card's body, for a surface whose sheet rows mirror its own rows
+     * (`giftUnwrap`: logo, brand, perk line, radio). The sheet still owns the card
+     * element, its radio semantics, listeners and data attributes. Defaults to the
+     * icon and perk label every other surface shows.
+     */
+    cardBody?: (card: HTMLElement, offer: Offer) => void;
+    /**
+     * The card's accessible name, for a `cardBody` whose visible order differs from the
+     * default card's (brand first). Defaults to `giftRowAccessibleName`, which matches
+     * the default body. Given so the name reads in the order the card shows its text.
+     */
+    cardLabel?: (offer: Offer) => string;
+    /**
+     * The CTA's label once a gift is picked. Defaults to `giftCtaLabel` ("Claim …"), which
+     * is right where the CTA claims. `giftUnwrap`'s only moves to its ready screen, so it
+     * passes a label that does not promise a claim.
+     */
+    ctaLabel?: (offer: Offer) => string;
+}
+export declare class GiftSheet {
+    #private;
+    constructor(options: GiftSheetOptions);
+    /**
+     * The sheet overlay.
+     *
+     * CATEGORY TABS ARE DATA-DRIVEN, and absent by default. The designs split this sheet
+     * into short groups ("Watch & listen", "Money", "Everyday"). `OfferModel.category` is
+     * read tolerantly from `campaign.category` (see `readProposedCategory`), each name is
+     * mapped onto a group by `giftCategoryGroup`, and the strip is only drawn when two
+     * groups each hold two or more of the listed offers (`sheetCategories`). Against a
+     * backend that sends no category that is never, and this sheet is the one list it
+     * always was. Nothing here derives a category from brand names or perk text: a guessed
+     * taxonomy looks like data and is wrong silently for the first publisher whose
+     * advertisers do not fit it.
+     */
+    render(): HTMLElement;
+    /**
+     * Rebuild the card list from `listed()`. The surface calls this after a promotion.
+     *
+     * Clears the pick: it may have just been promoted out of the list, and a CTA left
+     * enabled and still naming it would do nothing when pressed. The tabs are recomputed
+     * too, because a promotion swaps one offer in and one out and can change which
+     * categories the sheet holds; the selected tab survives when it still exists.
+     */
+    renderList(): void;
+    open(opener?: HTMLElement): void;
+    close(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=GiftSheet.d.ts.map

package/types/ui/GiftSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GiftSheet.d.ts","sourceRoot":"","sources":["../../src/ui/GiftSheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,eAAe,CAAC;AAKzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAM9C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAqB1E;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,EAAE,GAAG,iBAAiB,EAAE,CAU3F;AAKD,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IACzB,yEAAyE;IACzE,MAAM,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAChC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACjC,uFAAuF;IACvF,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,uFAAuF;IACvF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC;IACvC,wFAAwF;IACxF,WAAW,EAAE,cAAc,CAAC;IAC5B,oFAAoF;IACpF,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,kFAAkF;IAClF,MAAM,EAAE,WAAW,CAAC;IACpB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACrD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CACrC;AAED,qBAAa,SAAS;;gBAiCR,OAAO,EAAE,gBAAgB;IAKrC;;;;;;;;;;;;OAYG;IACH,MAAM,IAAI,WAAW;IAyHrB;;;;;;;OAOG;IACH,UAAU,IAAI,IAAI;IAsTlB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI;IAuChC,KAAK,IAAI,IAAI;IAqDb,OAAO,IAAI,IAAI;CAahB"}