@encorekit/web-sdk 2.0.7 → 2.1.1

package/types/ui/safeImageSrc.d.ts

@@ -11,5 +11,15 @@
  * relative and unparseable strings — is rejected. Callers fall back to their
  * placeholder (monogram tile / placeholder banner) on rejection.
  */
+/**
+ * Whether `hostname` is one of those local-dev hosts.
+ *
+ * A PREDICATE rather than the set itself, which is the point: this is a security
+ * allowlist, and exporting the container would hand every consumer a live handle able
+ * to `add()` to it at runtime — a `ReadonlySet` type would stop that in TypeScript
+ * only. Callers want the decision, not the data. Shared with the advertiser preconnect
+ * so the two cannot drift on what counts as local.
+ */
+export declare function isLoopbackHost(hostname: string): boolean;
 export declare function safeImageSrc(url: string | undefined): string | undefined;
 //# sourceMappingURL=safeImageSrc.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"safeImageSrc.d.ts","sourceRoot":"","sources":["../../src/ui/safeImageSrc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAaxE"}
+{"version":3,"file":"safeImageSrc.d.ts","sourceRoot":"","sources":["../../src/ui/safeImageSrc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAaxE"}

package/types/ui/styles.d.ts

@@ -26,6 +26,61 @@ export declare const BREAKPOINTS: {
  * track Figma frame 18304:2399 (393×852). Where they disagree the Figma wins — see
  * the PR for the itemised list. Web has no SDUI engine, so every value is hand-tracked.
  *
+ * REWARD_MOBILE_NOTES — the reward sheet below the 767px breakpoint.
+ *
+ * The composition is three bands in one flex column that fills the sheet: the status
+ * block (headline, subheadline) at the top, the carousel in the middle with
+ * `flex: 1 1 auto`, and the CTA stack pinned to the bottom with `margin-top: auto` over
+ * its own `max(31px, env(safe-area-inset-bottom))` padding. The carousel is the ONLY
+ * band that grows, and centres its cards and dots in whatever it is given, so every
+ * spare pixel on a tall phone goes to the middle rather than to a gap under the CTAs.
+ *
+ * History worth knowing before touching it. From 3.0.0 until this block was repaired,
+ * a stray `;` left behind when the `.thankyou-footer` selector was deleted turned the
+ * orphaned declarations after it into the prelude of one invalid rule whose body was
+ * this whole media block, so browsers dropped all of it (CSS Syntax, "consume a
+ * qualified rule"). The sheet's root therefore never filled the modal and the CTAs sat
+ * directly under the carousel with dead space beneath them, while the `margin-top:
+ * auto` on the action block — which is live — had no free space to claim.
+ *
+ * What the old block ALSO did, and why those parts were not revived: a `::before` on
+ * the root and an `::after` on the carousel split the slack 1:1.35 to float the whole
+ * stack optically centred. Both spacers are flex-grow items, and flex-grow resolves
+ * before auto margins, so they would have eaten the space the CTA pin needs and pushed
+ * the headline down. The `.thankyou::before` spacer would also have landed above the
+ * gift surfaces' heroes, which share this root class.
+ *
+ * `.carousel-cards` keeps `flex: 0 1 auto; min-height: 0`: on a sheet too short for
+ * the stack, the cards' padded scroll box gives up height before the CTAs are pushed
+ * off the bottom of an `overflow: hidden` sheet.
+ *
+ * GIFT_FLOW_NOTES — why the gift block in the stylesheet looks the way it does, and
+ * the reason it is a JS comment rather than a CSS one (see the paragraph above: prose
+ * inside the literal is payload every consumer downloads).
+ *
+ * The gift flow is the `rewardUsers` SELECTION surface: a box that opens, three rows,
+ * and a sheet for everything that did not fit. Its geometry is a single hand-tracked
+ * coordinate system — the numbers in the box rules are positions inside a 270×236
+ * stage and are meaningless apart from each other, so `GiftHero.ts` carries the table
+ * and this block carries the same values. Retuning one without the other detaches the
+ * lid from the box.
+ *
+ * ALL MOTION IS CSS, deliberately: four keyframes and a class toggle, no library, no
+ * per-frame JavaScript. The one canvas is the reward sheet's existing confetti, reused
+ * with a burst origin rather than reimplemented. The reduced-motion block does not
+ * merely disable the animation — it places the lid, bow and tiles in their FINAL
+ * state, because a gift box that never opens is a broken screen, not a calm one.
+ *
+ * COLOURS ARE FIXED, NOT THEMED — reversed on Junaid's call after the first build
+ * shipped a theme-tinted gift box. The palette is the design's own, pinned in the
+ * .thankyou--gift block and in the box rules as literals, because brand-derived
+ * tinting is iOS/Android behaviour and web following it here produced a saturated
+ * accent behind near-black row text that failed contrast outright. Highlights stay
+ * white at low alpha rather than a second hardcoded blue, so the box shades from one
+ * value. Publisher `appearance` overrides still win: they write inline styles, which
+ * outrank every rule here. What no longer reaches this surface is IMPLICIT theming —
+ * a `theme.primaryColor` from configure(), or the variant's brand colour.
+ *
  * SHEET BACKGROUND IS FLAT — a deliberate divergence from both the Figma and the
  * variant, on Junaid's call. The sheet used to layer the Figma's radial brand glow
  * over the variant's two stacked full-bleed gradients (an accent wash and a
@@ -67,6 +122,117 @@ export declare const BREAKPOINTS: {
  * the right and bottom edges (its decorative vector), derived from the same tint so
  * any advertiser colour works. See `brandTint.ts` for where the tint comes from.
  *
+ * THE ROWS ARRIVE WITH THE GIFTS, and each row lands on the same frame as its own
+ * tile. The hero's tiles settle at 1.08s / 1.15s / 1.22s (rise2 0.38 + 0.70, rise1
+ * 0.45 + 0.70, rise3 0.52 + 0.70), and the rows run 0.46s from 0.62 / 0.69 / 0.76 —
+ * the same three end times, carrying the tiles' own 0.07s stagger. Row 1 is the first
+ * offer, whose gift is the CENTRE tile (`SLOT_ORDER` puts it at t2, the earliest), so
+ * the pairing is real and not just a rhythm: each row finishes as its own gift does.
+ * They start at 0.62s, while the tiles are mid-flight and the lid (0.20-0.75) is still
+ * clearing, so the list reads as the consequence of the box opening rather than a
+ * second, later animation. The curve is `gift-rise`'s own — no new easing.
+ *
+ * THE ROWS ARE VISIBLE IF THE ANIMATION NEVER RUNS. This is the constraint that
+ * matters, and the reason the rule is written the way it is: the row's BASE state is
+ * the FINISHED state (opaque, untransformed, interactive), and the entrance is gated
+ * behind `.gift-hero--play`. No play class — a hidden tab, a throttled one, rAF that
+ * never fires — means the selector never matches and the rows simply sit there, usable.
+ * The hero follows the same rule. The tiles, lid and bow used to take the opposite bet
+ * (tiles at `opacity: 0` in their base rule, reaching 1 only through the animation's
+ * `forwards` fill), which is how an earlier revision shipped a closed box with three
+ * invisible gifts under a headline promising one, and how any host or extension rule
+ * forcing `animation: none` still could. Their base rules are now the OPEN box (lid and
+ * bow gone, tiles risen), the keyframes carry the closed state in an explicit `from`,
+ * and the fill is `both` so each part holds that `from` through its delay instead of
+ * showing its end state before it starts. The play class lands on the modal's first
+ * visible frame (rAF, same frame as the fade-in), so there is no flash of the open box.
+ *
+ * THE ACTION BLOCK ENTERS WITH THE ROWS, AND THAT IS A CORRECTNESS FIX, not a flourish.
+ * Staggering the rows left the CTA rendered, enabled and naming a specific gift for the
+ * whole reveal while no row was on screen. Measured: 400ms after the rows existed, with
+ * ZERO rows visible, the button reported disabled=0, opacity 1, visibility visible,
+ * pointer-events auto and a positive `elementFromPoint` hit — and tapping it resolved
+ * `show()` with `{status:"claimed"}`. A user could claim a named gift before being shown
+ * the choice, on a screen whose entire premise is picking one. The row entrance created
+ * that window (the rows used to be painted on the first frame), so it closes it.
+ *
+ * It is the FOURTH item on the same cadence — 0.62 / 0.69 / 0.76 for the rows, 0.83 for
+ * the block — landing at 1.29s, just after the last tile settles at 1.22s. The artifact
+ * is a STATIC mock and specifies no timing (its transcription in this file is values
+ * only), but it does put the rows and the CTA in one block below the hero, so the block
+ * enters as one and the cadence is the rows' own rather than something invented.
+ *
+ * `visibility: hidden` IS NOT ENOUGH ON ITS OWN HERE, and the difference nearly shipped.
+ * It suppresses hit-testing on the element it is computed on — a row animates itself,
+ * so a hidden row is genuinely unclickable (measured: hit=0 for the whole delay). The
+ * CTA is not the animated element; its BLOCK is. Measured in a WKWebView with the block
+ * at `visibility: hidden, opacity: 0`, `elementFromPoint` over the button still returned
+ * `BUTTON.encore-reward-cta-primary` — the parent's animated visibility did not stop the
+ * descendant being hit. So the keyframes also animate `pointer-events` (none -> auto),
+ * which is what actually makes a nested control unreachable. It is CSS rather than the
+ * `disabled` attribute on purpose — `disabled` would have to be removed
+ * by JS, and JS that never runs would leave a permanently dead claim button, which is
+ * the same trap in a worse place. With animations off the block is simply visible and
+ * live, because the base rule is the finished state. (A programmatic `.click()` bypasses
+ * hit-testing and still fires; that is not a user tap, and the harness measures the
+ * `elementFromPoint` hit rather than relying on it.)
+ *
+ * The block is never rebuilt — `RewardActions` is constructed once in `Encore.ts` and
+ * selection only rewrites its label — so it needs no `--intro` marker the way the rows
+ * do, and its entrance cannot replay.
+ *
+ * IT IS THE OPENING REVEAL, NOT A ROW STYLE, which is why the gate is `--intro` (set
+ * by the first `#renderRows` only) and not the row class. `#promote` rebuilds the
+ * container's children when a gift is pulled out of the sheet, and a NEW element
+ * matching an animation rule starts that animation from its hidden from-state.
+ * Measured in the webview by doing exactly what `#promote` does — clear the container,
+ * append rows — 2.5s after the box had settled: all three went `0/12/h/0` for 600ms
+ * and faded back in. Today the sheet's CTA claims immediately so a user would barely
+ * catch it, but `selectOffer`/`next()` are public and reach `#promote` without a claim.
+ *
+ * `visibility` is in the keyframes so no row is ever invisible-but-clickable: with
+ * `both` fill the backwards phase holds `hidden` through the delay, and visibility
+ * resolves to `visible` for the whole interpolation once the fade starts. Focus order
+ * is untouched — nothing is reordered, added or removed from the DOM, and the rows are
+ * built and appended exactly as before.
+ *
+ * REDUCED MOTION resets it to `animation: none`, and the reset REPEATS THE FULL
+ * SELECTOR: the block's existing `.gift-row` reset is one class, and at (0,1,0) it
+ * would lose to the gated (0,3,0) rule no matter where it sat in the file.
+ *
+ * THE TOP INSET IS A FLOOR, NOT A SUM, and it belongs to the surface, not the hero.
+ *
+ * `env(safe-area-inset-top)` is ZERO in a host app's in-app browser: the webview sits
+ * BELOW the host's header, so the host's chrome is under the notch and this page is
+ * not. Measured in a WKWebView on a 16 Pro — safeTop 0 on all four simulator sizes,
+ * 16 Pro Max included — every `calc(X + env(safe-area-inset-top))` in this file
+ * collapses to X there. A sum can only ADD to a floor it already has; it cannot supply
+ * one. Hence `max(22px, env(safe-area-inset-top))`, the same shape as the bottom inset
+ * on `.reward-actions`: 22px is the floor, and a real notch wins only where it is
+ * genuinely bigger (full-screen Safari reports 59 on the same page, which is why the
+ * bug survived every check made there).
+ *
+ * 22px is MEASURED, not chosen: it is the clearance the design's full-size hero put
+ * above the box (a 236px stage centred in a 280px hero), and it reproduces the
+ * artifact's 24px above the topmost tile once the tile's own 2px inset into the stage
+ * is added. The 16 Pro Max is the one device that stays above the 820px tier, so it
+ * alone draws the composition unshrunk — measured there, minTileTop 24.
+ *
+ * WHY THE SURFACE AND NOT THE HERO: `.thankyou--gift` owns the scrolling, so a notch
+ * taller than the floor pushes content down and the surface scrolls. The same padding
+ * on the fixed-height hero would drive the scaled box into the headline beneath it.
+ *
+ * AND EACH TIER PAYS FOR IT OUT OF ITS OWN HERO — 280→258, 216→194, 150→128 with the
+ * box scaled 0.62→0.54 so it still fits what is left. The inset therefore costs the
+ * column nothing: measured before and after, "Other gifts" sits at exactly the same
+ * offset on all four sizes (SE 592/610, 16 722/756, 16 Pro 741/775, Max 823/857),
+ * which matters because the SE has only 18px of headroom to begin with.
+ *
+ * Nothing ever placed space above the hero before this. `.thankyou-status` carries the
+ * 40px sheet inset, but this composition puts the hero ABOVE that block and zeroes the
+ * padding for exactly that reason, so the hero's only clearance was the centring slack
+ * — which the 820px tier removes when it top-aligns the stage.
+ *
  * DESKTOP WIDTH. The design is a 393-wide phone frame; on the desktop modal
  * (max-width 800) the content column holds 393 and centres, so the hero keeps its
  * proportions instead of stranding a 210px card in an 800px sheet. Content sits at

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

@@ -1 +1 @@
-{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/ui/styles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAGX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAC3C,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;;;;IAI/B,0FAA0F;;CAElF,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwgED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,cAAmB,GAAG,IAAI,CAgB7D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAMnC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAe1D;AAED;;GAEG;AACH,wBAAgB,EAAE,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7C"}
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/ui/styles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAGX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmOG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAC3C,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;;;;IAI/B,0FAA0F;;CAElF,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAi8HD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,cAAmB,GAAG,IAAI,CAgB7D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAMnC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAe1D;AAED;;GAEG;AACH,wBAAgB,EAAE,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/types/ui/termsLine.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The terms line under the primary CTA on the `giftList` and `giftUnwrap` surfaces:
+ * "By proceeding you agree to our offer terms", with "offer terms" underlined.
+ *
+ * It REPLACES the per-offer fine print on those two surfaces only. `giftReveal` keeps
+ * `GIFT_COPY.terms` through `RewardActions.termsText`, and the carousel keeps its trust
+ * line; neither calls this.
+ *
+ * WHERE "offer terms" GOES is the selected offer's `termsUrl` (`campaign.termsUrl`, an
+ * https URL the offer mapping has already vetted; it is checked again here). With one,
+ * the run is a real link that opens in a new tab; without one it is underlined PLAIN
+ * TEXT, matching the design, and not focusable, because an `<a>` with no destination
+ * is a control that does nothing. `setTermsLink` swaps the run as the selection moves,
+ * so the line is never a link to some other offer's terms.
+ *
+ * `onOpen` exists for a surface that has something real to open (a sheet it owns);
+ * given it, the link renders as a `<button>` and calls it. Nothing passes it today.
+ */
+export interface TermsLineOptions {
+    /**
+     * Opens whatever the surface shows as the offer terms. When present the link is a
+     * real `<button type="button">`; when absent it is non-interactive text. Errors it
+     * throws are contained so a terms tap can never throw into the host page.
+     */
+    onOpen?: () => void;
+    /** The selected offer's terms URL. https only; anything else renders as text. */
+    termsUrl?: string;
+}
+/** Builds `<p class="encore-gift-terms">…<a|span|button class="encore-gift-terms-link">`. */
+export declare function renderTermsLine(options?: TermsLineOptions): HTMLElement;
+/** Point the line's "offer terms" run at `termsUrl`, or back to plain text without one. */
+export declare function setTermsLink(line: HTMLElement, termsUrl: string | undefined): void;
+//# sourceMappingURL=termsLine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"termsLine.d.ts","sourceRoot":"","sources":["../../src/ui/termsLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,WAAW,CAQ3E;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKlF"}